xacpp 0.1.0

package/dist/esm/message.d.ts

@@ -0,0 +1,99 @@
+/**
+ * XACPP protocol messages — envelope layer design.
+ *
+ * Wire messages are uniformly `XacppEnvelope`, divided into two layers:
+ *
+ * - **Envelope layer**: `type` (routing) + `id` (correlation) + `payload` (business content)
+ * - **Payload layer**: `XacppRequest` / `XacppResponse`
+ *
+ * Transport handles envelope packing/unpacking and id correlation; upper layers only operate on payloads.
+ *
+ * ## JSON format examples
+ *
+ * ```json
+ * Request (Command): {"id":"r1","type":"request","payload":{"kind":"command","payload":{"establish":{"credentials":null}}}}
+ * Response (Established): {"id":"r1","type":"response","payload":{"kind":"established","sessionId":"s1"}}
+ * ```
+ */
+import type { XacppCommand } from "./commands";
+import type { ActionResponse, QuestionResponse, SensitiveInfoOperationResponse, XacppEvent } from "./events";
+/** XACPP error. */
+export declare class XacppError extends Error {
+    /** Machine-readable error code. */
+    readonly code: string;
+    constructor(code: string, message: string);
+    /** Connection error: not connected. */
+    static notConnected(): XacppError;
+    /** Connection error: already connected. */
+    static alreadyConnected(): XacppError;
+    /** Connection error: connection closed. */
+    static closed(): XacppError;
+    /** Processing error: no handler registered. */
+    static noHandler(): XacppError;
+    /** Processing error: handler internal error. */
+    static internal(message: string): XacppError;
+    /** Application-layer custom error. */
+    static application(code: string, message: string): XacppError;
+    /** Processing error: request payload unparseable. */
+    static invalidRequest(message: string): XacppError;
+    /** Handshake rejected. */
+    static establishReject(reason: string): XacppError;
+}
+/** Request payload. Accepted by Transport's `send` method. */
+export type XacppRequest = {
+    kind: "command";
+    payload: XacppCommand;
+} | {
+    kind: "event";
+    payload: XacppEvent;
+};
+/** Response payload. Returned by Transport's `send` method. */
+export type XacppResponse = 
+/** Handshake success: issues session identifier and credentials. */
+{
+    kind: "established";
+    sessionId: string;
+    credentials?: string;
+}
+/** Handshake rejected. */
+ | {
+    kind: "establish_reject";
+    reason: string;
+}
+/** Tool call authorization response. */
+ | {
+    kind: "action";
+    requestId: string;
+} & ActionResponse
+/** User question response. */
+ | {
+    kind: "question";
+    requestId: string;
+} & QuestionResponse
+/** Sensitive info operation response (flatten: response fields spread to top level). */
+ | {
+    kind: "sensitive_info_operation";
+    requestId: string;
+} & SensitiveInfoOperationResponse
+/** Generic acknowledge: request processed successfully, no data returned. */
+ | {
+    kind: "acknowledge";
+}
+/** Processing failure. */
+ | {
+    kind: "error";
+    code: string;
+    message: string;
+};
+/** Wire message. Envelope layer handles routing. */
+export type XacppEnvelope = {
+    type: "request";
+    id: string;
+    session_id?: string;
+    payload: XacppRequest;
+} | {
+    type: "response";
+    id: string;
+    session_id?: string;
+    payload: XacppResponse;
+};

package/dist/esm/peer.d.ts

@@ -0,0 +1,79 @@
+/**
+ * XACPP Peer — protocol layer endpoint.
+ *
+ * ## Responsibility
+ *
+ * Peer is a protocol layer entity representing one endpoint in the communication link. Core responsibilities:
+ *
+ * - **Typed operations**: encapsulate Transport's payload-layer API into semantically clear Command / Event operations
+ * - **Protocol state machine**: manage connection state
+ * - **Session routing**: route inbound requests to the corresponding Session's handler by session_id
+ *
+ * ## Boundary with Transport
+ *
+ * Peer holds `XacppTransport` (composition), delegating all low-level IO to Transport.
+ * Peer does not care about envelope id, encoding/decoding, request-response correlation (all encapsulated by Transport).
+ *
+ * ```text
+ * ┌──────────────────────────────────────────────────────────────┐
+ * │  Peer (protocol layer)                                       │
+ * │  Typed operations: request_command / request_event           │
+ * │  Session routing: session_id → XacppSessionHandler          │
+ * ├──────────────────────────────────────────────────────────────┤
+ * │  Session (session layer)                                     │
+ * │  Holds XacppSessionHandler, sends directly to Transport      │
+ * │  Does not go through Peer                                    │
+ * ├──────────────────────────────────────────────────────────────┤
+ * │  Transport (transport layer)                                 │
+ * │  Single semantic: send (request-response), caller chooses    │
+ * │  whether to wait for response                                │
+ * │  Internals: envelope packing/unpacking (id correlation),     │
+ * │  encoding/decoding, pending matching                         │
+ * │  Unaware of specific business event types                    │
+ * └──────────────────────────────────────────────────────────────┘
+ * ```
+ */
+import type { XacppTransport } from "./transport";
+import type { XacppCommand } from "./commands";
+import type { XacppEvent } from "./events";
+import type { XacppResponse } from "./message";
+import type { EstablishHandler, XacppSessionHandler } from "./handler";
+import { XacppSession } from "./session";
+/** Peer protocol state. */
+export declare enum PeerState {
+    /** Not connected / connection closed. */
+    Disconnected = "disconnected",
+    /** Communication channel established, ready to create logical sessions. */
+    Connected = "connected"
+}
+/** XACPP protocol endpoint.
+ *
+ * Each communication party holds a `XacppPeer` instance, exchanging messages via a shared Transport.
+ */
+export declare class XacppPeer {
+    private transport;
+    private _state;
+    private sessions;
+    private establishHandler;
+    constructor(transport: XacppTransport, establishHandler: EstablishHandler);
+    /** Current protocol state. */
+    get state(): PeerState;
+    /** Establish connection.
+     *
+     * Registers routing closure with Transport, then starts the underlying communication channel.
+     * On success, state transitions to `Connected`; subsequent `establish` calls can create logical sessions.
+     */
+    connect(): Promise<void>;
+    /** Establish logical session.
+     *
+     * Sends Establish command to peer, carrying optional auth credentials and session handler.
+     * Handler is registered in Peer routing table; Session is responsible for sending.
+     */
+    establish(credentials: string | null, handler: XacppSessionHandler): Promise<XacppSession>;
+    /** Disconnect. */
+    disconnect(): Promise<void>;
+    /** Send command and wait for response (no session context). */
+    requestCommand(sessionId: string | null, command: XacppCommand): Promise<XacppResponse>;
+    /** Send interactive event and wait for response (no session context). */
+    requestEvent(sessionId: string | null, event: XacppEvent): Promise<XacppResponse>;
+}

package/dist/esm/session.d.ts

@@ -0,0 +1,34 @@
+/**
+ * XACPP logical session.
+ *
+ * Created via `XacppPeer.establish`, holds an independent session_id and credentials.
+ * Multiple Sessions under the same Peer share the same connection.
+ */
+import type { XacppTransport } from "./transport";
+import type { XacppCommand } from "./commands";
+import type { XacppEvent } from "./events";
+import type { XacppResponse } from "./message";
+/** XACPP logical session.
+ *
+ * Created via `XacppPeer.establish`, holds an independent session_id and credentials.
+ * Multiple Sessions under the same Peer share the same connection.
+ */
+export declare class XacppSession {
+    private transport;
+    private _sessionId;
+    private _credentials;
+    /** @internal Created by XacppPeer.establish. */
+    constructor(transport: XacppTransport, sessionId: string, credentials: string | null);
+    /** Session identifier. */
+    get sessionId(): string;
+    /**
+     * Credentials issued by the responder.
+     *
+     * Caller can save them for use in subsequent `establish` calls.
+     */
+    get credentials(): string | null;
+    /** Send command and wait for response. */
+    requestCommand(command: XacppCommand): Promise<XacppResponse>;
+    /** Send event and wait for response. */
+    requestEvent(event: XacppEvent): Promise<XacppResponse>;
+}

package/dist/esm/socket-transport.d.ts

@@ -0,0 +1,35 @@
+import * as net from "node:net";
+import type { RequestHandler, XacppTransport } from "./transport";
+import type { XacppRequest, XacppResponse } from "./message";
+export declare class SocketTransport implements XacppTransport {
+    private socket;
+    private handler;
+    private pending;
+    private nextId;
+    private _connected;
+    private _exhausted;
+    private writeQueue;
+    private inflight;
+    private port?;
+    private host?;
+    private rl;
+    /** Client mode: connect() initiates a TCP connection to the specified address. */
+    static connectTo(port: number, host?: string): SocketTransport;
+    /** Server mode: use an already-accepted Socket. */
+    constructor(socket?: net.Socket);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    send(sessionId: string | null, payload: XacppRequest): Promise<XacppResponse>;
+    onRequest(handler: RequestHandler): void;
+    private onFrame;
+    /** Handle inbound request: spawn-per-request, does not await. */
+    private dispatchRequest;
+    /** Serialize and send envelope (write-protected: promise chain serialization).
+     *
+     * Returns only the promise for the current write, not the entire chain.
+     * Chain always continues (even if a write fails), ensuring subsequent writes are not blocked.
+     */
+    private writeEnvelope;
+    private rejectAllPending;
+    private cleanup;
+}

package/dist/esm/stdio-transport.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Stdio Transport implementation.
+ *
+ * Communicates via stdin/stdout pipe handles using JSONL frame protocol (one message per line, separated by `\n`).
+ */
+import type { RequestHandler, XacppTransport } from "./transport";
+import type { XacppRequest, XacppResponse } from "./message";
+/** Stdio Transport implementation. */
+export declare class StdioTransport implements XacppTransport {
+    private writer;
+    private reader;
+    private rl;
+    private _connected;
+    private _exhausted;
+    /** Handler registration. */
+    private requestHandler;
+    /** Pending map: id → { resolve, reject }. */
+    private pending;
+    /** Auto-incrementing id. */
+    private nextId;
+    constructor(writer: NodeJS.WritableStream, reader: NodeJS.ReadableStream);
+    private genId;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    send(sessionId: string | null, payload: XacppRequest): Promise<XacppResponse>;
+    onRequest(handler: RequestHandler): void;
+    /** Process a frame received from the wire. */
+    private onFrame;
+    /** Handle inbound request envelope: dispatch handler, send response. */
+    private handleRequest;
+    /** Handle inbound response envelope: match pending. */
+    private handleResponse;
+    /** Serialize and send envelope. Returns whether write succeeded. */
+    private writeEnvelope;
+    /** Cleanup on connection close. */
+    private cleanup;
+}

package/dist/esm/transport.d.ts

@@ -0,0 +1,61 @@
+/**
+ * XACPP Transport abstraction.
+ *
+ * ## Responsibility
+ *
+ * Transport unifies the underlying communication channel (stdio / TCP / WebSocket) into `send` semantics:
+ *
+ * - **send**: send request payload, wait for response payload to return. Caller can spawn to background if response is not needed.
+ * - **accept**: listen for peer requests, dispatch via `onRequest` callback,
+ *   which receives session_id + payload; the return value is automatically sent back as a response.
+ *
+ * Transport internals:
+ *
+ * - **Envelope packing/unpacking**: auto-assign request id, pack into envelope for sending, unpack to return payload
+ * - **Request-response correlation**: match pending sends by id upon receiving a Response
+ * - **Encoding/decoding**: serialization / deserialization (JSONL)
+ * - **Connection management**: establish / tear down underlying communication channel
+ *
+ * ## Layer boundary
+ *
+ * - **Transport to upper layer**: exposes `send` / `onRequest`,
+ *   does not expose raw byte send/receive, envelope id, or encoding/decoding details
+ * - **Peer to upper layer**: exposes typed `requestCommand` / `requestEvent`
+ *   and session routing mechanism
+ *
+ * ## accept semantics
+ *
+ * Transport listens for peer input, delivering (session_id, payload) to registered callbacks.
+ * Handler returning `XacppResponse` indicates successful processing;
+ * throwing `XacppError` indicates processing failure (Transport auto-constructs an Error response and sends it back).
+ *
+ * ## Error semantics
+ *
+ * **Connection-level throw = connection unavailable**. All fault-tolerance logic is encapsulated inside the Transport implementation.
+ * Upper layer only needs one rule: method throw means connection error.
+ */
+import type { XacppRequest, XacppResponse } from "./message";
+/** Transport layer request handler callback type. */
+export type RequestHandler = (sessionId: string | null, payload: XacppRequest) => Promise<XacppResponse>;
+/** XACPP transport layer abstraction. */
+export interface XacppTransport {
+    /** Establish the underlying communication channel and start the accept loop. */
+    connect(): Promise<void>;
+    /** Tear down the underlying communication channel. */
+    disconnect(): Promise<void>;
+    /**
+     * Send request payload and wait for response.
+     *
+     * Transport auto-assigns id, packs envelope, serializes and sends, registers pending, waits for response, unpacks and returns payload.
+     * Caller can skip await if response is not needed.
+     */
+    send(sessionId: string | null, payload: XacppRequest): Promise<XacppResponse>;
+    /**
+     * Register request callback (unified for Command and Event).
+     *
+     * Must be called before `connect`, otherwise throws XacppError(AlreadyConnected).
+     * When handler returns `Ok`, Transport auto-packs into same-id envelope and sends back;
+     * when handler throws, Transport auto-constructs an Error response and sends back.
+     */
+    onRequest(handler: RequestHandler): void;
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "xacpp",
+  "version": "0.1.0",
+  "description": "Agent Control Plane Protocol — TypeScript implementation",
+  "keywords": [
+    "xacpp",
+    "acpp",
+    "protocol",
+    "communication",
+    "peer"
+  ],
+  "author": "drodreo",
+  "license": "MIT",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.mjs",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.mjs"
+      },
+      "require": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rslib build",
+    "prepublishOnly": "rslib build",
+    "test": "vitest run"
+  },
+  "packageManager": "pnpm@10.33.0",
+  "devDependencies": {
+    "@rslib/core": "^0.21.5",
+    "@types/node": "^25.7.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  }
+}