@personaxis/protocol 0.11.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Personaxis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/client.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Front-end side: connect to an engine endpoint, submit Ops, receive events.
+ * Deliberately tiny — a TUI, a headless script, or a test all use the same
+ * three calls: `connect`, `submit`, `onEvent`.
+ */
+import { type EventMsg, type Op, type OpResult } from "./types.js";
+export declare class ProtocolClient {
+    private socket;
+    private conn;
+    private readonly listeners;
+    /** The engine's protocol version, known after connect() resolves. */
+    serverProtocolVersion: number | null;
+    connect(pipePath: string, timeoutMs?: number): Promise<void>;
+    /** Submit an operation; resolves with the engine's result. */
+    submit(op: Op): Promise<OpResult>;
+    /** Subscribe to engine events; returns the unsubscribe function.
+     * Subscribe BEFORE connect() — greeting events arrive during the handshake. */
+    onEvent(listener: (e: EventMsg) => void): () => void;
+    close(): void;
+}

package/dist/client.js

@@ -0,0 +1,62 @@
+/**
+ * Front-end side: connect to an engine endpoint, submit Ops, receive events.
+ * Deliberately tiny — a TUI, a headless script, or a test all use the same
+ * three calls: `connect`, `submit`, `onEvent`.
+ */
+import { createConnection } from "node:net";
+import { RPC_EVENT, RPC_HELLO, RPC_SUBMIT, } from "./types.js";
+import { connectionFor } from "./wire.js";
+export class ProtocolClient {
+    socket = null;
+    conn = null;
+    listeners = new Set();
+    /** The engine's protocol version, known after connect() resolves. */
+    serverProtocolVersion = null;
+    async connect(pipePath, timeoutMs = 5_000) {
+        await new Promise((resolve, reject) => {
+            const socket = createConnection(pipePath);
+            const timer = setTimeout(() => {
+                socket.destroy();
+                reject(new Error(`timed out connecting to engine at ${pipePath}`));
+            }, timeoutMs);
+            socket.once("error", (err) => {
+                clearTimeout(timer);
+                reject(err);
+            });
+            socket.once("connect", () => {
+                clearTimeout(timer);
+                this.socket = socket;
+                this.conn = connectionFor(socket);
+                this.conn.onNotification(RPC_EVENT, (e) => {
+                    for (const l of this.listeners)
+                        l(e);
+                });
+                this.conn.listen();
+                resolve();
+            });
+        });
+        // Handshake: version exchange AND registration barrier — once this request
+        // roundtrips, the server has registered us and broadcasts will arrive.
+        const hello = (await this.conn.sendRequest(RPC_HELLO));
+        this.serverProtocolVersion = hello.protocolVersion;
+    }
+    /** Submit an operation; resolves with the engine's result. */
+    submit(op) {
+        if (!this.conn)
+            return Promise.reject(new Error("not connected"));
+        return this.conn.sendRequest(RPC_SUBMIT, op);
+    }
+    /** Subscribe to engine events; returns the unsubscribe function.
+     * Subscribe BEFORE connect() — greeting events arrive during the handshake. */
+    onEvent(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    close() {
+        this.conn?.dispose();
+        this.socket?.destroy();
+        this.conn = null;
+        this.socket = null;
+        this.listeners.clear();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @personaxis/protocol — the UI↔engine seam (SQ/EQ over JSON-RPC 2.0).
+ *
+ * Codex's protocol pattern adapted to TypeScript: front-ends submit typed
+ * operations and consume typed events; the engine never renders and a
+ * front-end never mutates persona state directly. One transport API on both
+ * OSes (UDS / Windows named pipes via node:net + vscode-jsonrpc).
+ */
+export { PROTOCOL_VERSION, RPC_SUBMIT, RPC_EVENT, RPC_HELLO, type HelloResult, type Op, type OpName, type OpResult, type EventMsg, type EventName, } from "./types.js";
+export { pipePathFor, connectionFor, type MessageConnection } from "./wire.js";
+export { ProtocolServer, type OpHandler } from "./server.js";
+export { ProtocolClient } from "./client.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * @personaxis/protocol — the UI↔engine seam (SQ/EQ over JSON-RPC 2.0).
+ *
+ * Codex's protocol pattern adapted to TypeScript: front-ends submit typed
+ * operations and consume typed events; the engine never renders and a
+ * front-end never mutates persona state directly. One transport API on both
+ * OSes (UDS / Windows named pipes via node:net + vscode-jsonrpc).
+ */
+export { PROTOCOL_VERSION, RPC_SUBMIT, RPC_EVENT, RPC_HELLO, } from "./types.js";
+export { pipePathFor, connectionFor } from "./wire.js";
+export { ProtocolServer } from "./server.js";
+export { ProtocolClient } from "./client.js";

package/dist/server.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Engine-side endpoint: accepts front-end connections, dispatches Ops to a
+ * single handler (the engine), broadcasts EventMsg to every connected front.
+ *
+ * The server holds NO business logic — governance, clamping and memory live in
+ * @personaxis/core behind the handler. This file is only the seam.
+ */
+import { type EventMsg, type Op, type OpResult } from "./types.js";
+import { type MessageConnection } from "./wire.js";
+export type OpHandler = (op: Op) => Promise<OpResult> | OpResult;
+export declare class ProtocolServer {
+    private readonly handler;
+    private server;
+    private readonly connections;
+    private readonly sockets;
+    constructor(handler: OpHandler);
+    /** Bind the endpoint. On POSIX a stale socket file from a crash is removed. */
+    listen(pipePath: string, onConfigured?: (conn: MessageConnection) => void): Promise<void>;
+    /** Broadcast an event to every connected front-end (JSON-RPC notification). */
+    broadcast(event: EventMsg): void;
+    /** Send to ONE connection (e.g. the session.configured greeting). */
+    send(conn: MessageConnection, event: EventMsg): void;
+    get connectionCount(): number;
+    close(): Promise<void>;
+}

package/dist/server.js

@@ -0,0 +1,93 @@
+/**
+ * Engine-side endpoint: accepts front-end connections, dispatches Ops to a
+ * single handler (the engine), broadcasts EventMsg to every connected front.
+ *
+ * The server holds NO business logic — governance, clamping and memory live in
+ * @personaxis/core behind the handler. This file is only the seam.
+ */
+import { createServer } from "node:net";
+import { existsSync, unlinkSync } from "node:fs";
+import { PROTOCOL_VERSION, RPC_EVENT, RPC_HELLO, RPC_SUBMIT, } from "./types.js";
+import { connectionFor } from "./wire.js";
+export class ProtocolServer {
+    handler;
+    server = null;
+    connections = new Set();
+    sockets = new Set();
+    constructor(handler) {
+        this.handler = handler;
+    }
+    /** Bind the endpoint. On POSIX a stale socket file from a crash is removed. */
+    listen(pipePath, onConfigured) {
+        if (process.platform !== "win32" && existsSync(pipePath)) {
+            // A previous engine that crashed leaves the UDS file behind; net.listen
+            // would EADDRINUSE forever. Named pipes on Windows self-clean.
+            try {
+                unlinkSync(pipePath);
+            }
+            catch {
+                /* raced with another cleanup — listen() will surface a real conflict */
+            }
+        }
+        this.server = createServer((socket) => {
+            const conn = connectionFor(socket);
+            // Handshake barrier: answered by the transport AFTER registration, so a
+            // client whose hello resolved is guaranteed to receive broadcasts.
+            conn.onRequest(RPC_HELLO, () => ({ protocolVersion: PROTOCOL_VERSION }));
+            conn.onRequest(RPC_SUBMIT, async (op) => {
+                try {
+                    return await this.handler(op);
+                }
+                catch (e) {
+                    // A handler bug must not tear down the transport for every front-end.
+                    return { ok: false, error: e.message };
+                }
+            });
+            conn.onClose(() => this.connections.delete(conn));
+            socket.on("close", () => this.sockets.delete(socket));
+            conn.listen();
+            this.connections.add(conn);
+            this.sockets.add(socket);
+            onConfigured?.(conn);
+        });
+        return new Promise((resolve, reject) => {
+            this.server.once("error", reject);
+            this.server.listen(pipePath, () => resolve());
+        });
+    }
+    /** Broadcast an event to every connected front-end (JSON-RPC notification). */
+    broadcast(event) {
+        for (const conn of this.connections) {
+            // Best-effort per connection: one dead front must not stop the others.
+            try {
+                void conn.sendNotification(RPC_EVENT, event);
+            }
+            catch {
+                this.connections.delete(conn);
+            }
+        }
+    }
+    /** Send to ONE connection (e.g. the session.configured greeting). */
+    send(conn, event) {
+        void conn.sendNotification(RPC_EVENT, event);
+    }
+    get connectionCount() {
+        return this.connections.size;
+    }
+    close() {
+        for (const conn of this.connections)
+            conn.dispose();
+        this.connections.clear();
+        // net.Server.close waits for every socket to END — destroy them so close()
+        // resolves even when a front-end never disconnected (crash, test teardown).
+        for (const socket of this.sockets)
+            socket.destroy();
+        this.sockets.clear();
+        return new Promise((resolve) => {
+            if (!this.server)
+                return resolve();
+            this.server.close(() => resolve());
+            this.server = null;
+        });
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The SQ/EQ vocabulary — the ONLY types a front-end and the engine share.
+ *
+ * Pattern from Codex (codex-rs/core/src/protocol.rs), adapted to TypeScript
+ * discriminated unions:
+ *   - Op        (submission queue): everything a front-end may ASK the engine.
+ *   - EventMsg  (event queue): everything the engine TELLS its front-ends.
+ *
+ * The engine's internal LoopEvent (core EventBus) is carried verbatim inside
+ * `engine.event` — the protocol does not re-model the living loop, it
+ * transports it. Type-only import: nothing from core lands in the wire bundle.
+ */
+import type { LoopEvent } from "@personaxis/core";
+export declare const PROTOCOL_VERSION = 1;
+export type Op = 
+/** Free-form user input for the living session (NL or /command line). */
+{
+    op: "user_input";
+    text: string;
+}
+/** One governed Living-Loop tick on an observation. */
+ | {
+    op: "observe";
+    observation: string;
+    source: "user" | "tool" | "internal" | "synthesis";
+}
+/** Clamped, audited state mutation (adjust_persona_state). */
+ | {
+    op: "adjust";
+    field: string;
+    delta: number;
+    reason: string;
+}
+/** Answer to a pending `approval.requested` event. */
+ | {
+    op: "approval";
+    requestId: string;
+    decision: "allow" | "deny";
+}
+/** Cancel the in-flight turn/agent run (best-effort). */
+ | {
+    op: "interrupt";
+}
+/** Current envelope values + recent mutations. */
+ | {
+    op: "state_get";
+}
+/** Mutation log + memory-chain integrity + anomalies. */
+ | {
+    op: "audit_get";
+}
+/** Change the self-improvement posture (governed; min-wins vs policy.yaml). */
+ | {
+    op: "improve";
+    mode: "locked" | "suggesting" | "autonomous";
+}
+/** Graceful engine shutdown (flushes writers, acks, then exits). */
+ | {
+    op: "shutdown";
+};
+export type OpName = Op["op"];
+/** Every op resolves to a result (JSON-RPC request/response). */
+export interface OpResult {
+    ok: boolean;
+    /** Op-specific payload (state snapshot, audit view, applied mutation, …). */
+    data?: unknown;
+    error?: string;
+}
+export type EventMsg = 
+/** First event on connect: who is being served, under which posture. */
+{
+    event: "session.configured";
+    sessionId: string;
+    persona: {
+        name: string;
+        path: string;
+    };
+    mode: "locked" | "suggesting" | "autonomous";
+    protocolVersion: number;
+}
+/** A turn began processing (user input or observation accepted). */
+ | {
+    event: "turn.started";
+    turnId: string;
+}
+/** Streaming text for the live region (frame-batched by the UI, not here). */
+ | {
+    event: "token.delta";
+    turnId: string;
+    text: string;
+}
+/** The turn finished; the transcript line can be committed to <Static>. */
+ | {
+    event: "turn.completed";
+    turnId: string;
+}
+/** A tool call needs a human decision — answer with op `approval`. */
+ | {
+    event: "approval.requested";
+    requestId: string;
+    tool: string;
+    args: Record<string, unknown>;
+    reason: string;
+}
+/** An engine LoopEvent, verbatim (observe/appraise/govern/mutate/memory/…). */
+ | {
+    event: "engine.event";
+    payload: LoopEvent;
+}
+/** Push snapshot after a mutation batch (dashboards re-render from this). */
+ | {
+    event: "state.snapshot";
+    values: Record<string, number>;
+    mutationCount: number;
+}
+/** Engine-side failure that did not kill the session. */
+ | {
+    event: "error";
+    message: string;
+};
+export type EventName = EventMsg["event"];
+/** All ops travel as ONE request method; the union discriminates. */
+export declare const RPC_SUBMIT = "personaxis/submit";
+/** All events travel as ONE notification method; the union discriminates. */
+export declare const RPC_EVENT = "personaxis/event";
+/**
+ * Connection handshake, answered by the transport itself (not the app handler).
+ * Doubles as the registration barrier: when it resolves, the server side has
+ * fully registered the connection — a subsequent broadcast WILL reach it.
+ */
+export declare const RPC_HELLO = "personaxis/hello";
+export interface HelloResult {
+    protocolVersion: number;
+}

package/dist/types.js

@@ -0,0 +1,24 @@
+/**
+ * The SQ/EQ vocabulary — the ONLY types a front-end and the engine share.
+ *
+ * Pattern from Codex (codex-rs/core/src/protocol.rs), adapted to TypeScript
+ * discriminated unions:
+ *   - Op        (submission queue): everything a front-end may ASK the engine.
+ *   - EventMsg  (event queue): everything the engine TELLS its front-ends.
+ *
+ * The engine's internal LoopEvent (core EventBus) is carried verbatim inside
+ * `engine.event` — the protocol does not re-model the living loop, it
+ * transports it. Type-only import: nothing from core lands in the wire bundle.
+ */
+export const PROTOCOL_VERSION = 1;
+// ─── JSON-RPC method names (the wire contract) ───────────────────────────────
+/** All ops travel as ONE request method; the union discriminates. */
+export const RPC_SUBMIT = "personaxis/submit";
+/** All events travel as ONE notification method; the union discriminates. */
+export const RPC_EVENT = "personaxis/event";
+/**
+ * Connection handshake, answered by the transport itself (not the app handler).
+ * Doubles as the registration barrier: when it resolves, the server side has
+ * fully registered the connection — a subsequent broadcast WILL reach it.
+ */
+export const RPC_HELLO = "personaxis/hello";

package/dist/wire.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Wire transport: JSON-RPC 2.0 over node:net.
+ *
+ * One API for both OSes (the vscode-jsonrpc + node:net combination VS Code
+ * battle-tested): Unix domain sockets on POSIX, named pipes on Windows.
+ * The path derives from the persona path so several personas can each run
+ * their own engine concurrently on one machine.
+ */
+import type { Socket } from "node:net";
+import { type MessageConnection } from "vscode-jsonrpc/node.js";
+/** Deterministic per-persona endpoint (named pipe on win32, UDS elsewhere). */
+export declare function pipePathFor(personaPath: string): string;
+/** JSON-RPC connection over an established socket (either side). */
+export declare function connectionFor(socket: Socket): MessageConnection;
+export type { MessageConnection };

package/dist/wire.js

@@ -0,0 +1,24 @@
+/**
+ * Wire transport: JSON-RPC 2.0 over node:net.
+ *
+ * One API for both OSes (the vscode-jsonrpc + node:net combination VS Code
+ * battle-tested): Unix domain sockets on POSIX, named pipes on Windows.
+ * The path derives from the persona path so several personas can each run
+ * their own engine concurrently on one machine.
+ */
+import { createHash } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createMessageConnection, StreamMessageReader, StreamMessageWriter, } from "vscode-jsonrpc/node.js";
+/** Deterministic per-persona endpoint (named pipe on win32, UDS elsewhere). */
+export function pipePathFor(personaPath) {
+    const h = createHash("sha256").update(personaPath).digest("hex").slice(0, 12);
+    if (process.platform === "win32")
+        return `\\\\.\\pipe\\personaxis-${h}`;
+    const runtimeDir = process.env.XDG_RUNTIME_DIR ?? tmpdir();
+    return join(runtimeDir, `personaxis-${h}.sock`);
+}
+/** JSON-RPC connection over an established socket (either side). */
+export function connectionFor(socket) {
+    return createMessageConnection(new StreamMessageReader(socket), new StreamMessageWriter(socket));
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@personaxis/protocol",
+  "version": "0.11.0",
+  "description": "The UI↔engine seam for Personaxis: typed operations (SQ) and events (EQ) as discriminated unions, carried over JSON-RPC 2.0 on node:net (Unix domain sockets + Windows named pipes, one API). The engine never renders; a front-end never mutates state directly — everything crosses this boundary.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "vscode-jsonrpc": "^8.2.1",
+    "@personaxis/core": "0.11.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/personaxis/cli.git",
+    "directory": "packages/protocol"
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}