xacpp 0.1.0

package/dist/esm/events/payload.d.ts

@@ -0,0 +1,51 @@
+/** 事件载荷类型。 */
+import type { ContentPart } from "./content";
+/** 内容分片事件载荷。 */
+export interface ContentPartEvent {
+    round: string;
+    pair: string;
+    payload: ContentPart;
+}
+/** 内容增量事件载荷。 */
+export interface ContentDeltaEvent {
+    round: string;
+    pair: string;
+    payload: ContentPart;
+}
+/** 可追踪事件载荷（Info/Warn/Error 共用）。 */
+export interface TraceableEvent {
+    title: string;
+    content: string;
+}
+/** 授权请求 Alert 级别。 */
+export type AlertLevel = "info" | "warn" | "critical";
+/** 工具调用开始事件载荷。 */
+export interface ToolUseEvent {
+    requestId: string;
+    toolName: string;
+    index: number;
+    arguments: string;
+}
+/** 工具调用结束事件载荷。 */
+export interface ToolResultEvent {
+    requestId: string;
+    toolName: string;
+    index: number;
+    parts: ContentPart[];
+}
+/** 安全告警事件载荷。 */
+export interface SecurityAlertEvent {
+    eventId: string;
+    toolName: string;
+    alertLevel: AlertLevel;
+    description: string;
+    threatType?: string;
+    matchedPattern?: string;
+    contextSnippet?: string;
+}
+/** SubActivity 任务启动事件载荷。 */
+export interface ActivityStartEvent {
+    goal: string;
+    activityId: string;
+    metadata?: Record<string, string>;
+}

package/dist/esm/events/upload.d.ts

@@ -0,0 +1,25 @@
+/** 文件上传与令牌用量。 */
+import type { FileRef } from "./content";
+/** 文件上传事件。 */
+export type UploadEvent = {
+    upload_event: "progress";
+    name: string;
+    uploaded: number;
+    total: number;
+} | {
+    upload_event: "completed";
+    name: string;
+    mediaSource: FileRef;
+} | {
+    upload_event: "error";
+    name: string;
+    error: string;
+};
+/** 令牌使用情况。 */
+export interface TokenUsage {
+    id: string;
+    message: string;
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}

package/dist/esm/events/xacpp_event.d.ts

@@ -0,0 +1,105 @@
+/**
+ * ACPP protocol event union type.
+ *
+ * Standardized event stream between the initiator and the peer.
+ * The only terminal signal is `complete`; all other events carry no implicit termination semantics.
+ */
+import type { ContentPart } from "./content";
+import type { ActionRequestEvent, NotifyEvent, QuestionEvent, SensitiveInfoOperationEvent } from "./interaction";
+import type { ActivityStartEvent, SecurityAlertEvent, ToolResultEvent, ToolUseEvent, TraceableEvent } from "./payload";
+import type { TokenUsage, UploadEvent } from "./upload";
+/** Unified multimodal content delta event. */
+export interface ContentDeltaXacppEvent {
+    type: "content_delta";
+    round: string;
+    pair: string;
+    payload: ContentPart;
+}
+/** Unified multimodal content part event. */
+export interface ContentPartXacppEvent {
+    type: "content_part";
+    round: string;
+    pair: string;
+    payload: ContentPart;
+}
+/** Thinking text output (delta). */
+export interface ThinkXacppEvent {
+    type: "think";
+    content: string;
+}
+/** System info output. */
+export interface InfoXacppEvent extends TraceableEvent {
+    type: "info";
+}
+/** System warning output. */
+export interface WarnXacppEvent extends TraceableEvent {
+    type: "warn";
+}
+/** Structured error event (non-terminal). */
+export interface ErrorXacppEvent extends TraceableEvent {
+    type: "error";
+}
+/** Tool call authorization request. */
+export interface ActionRequestXacppEvent extends ActionRequestEvent {
+    type: "action_request";
+}
+/** User notification (one-way push). */
+export interface NotifyXacppEvent extends NotifyEvent {
+    type: "notify";
+}
+/** User question. */
+export interface QuestionXacppEvent extends QuestionEvent {
+    type: "question";
+}
+/** Sensitive information operation request. */
+export interface SensitiveInfoOperationXacppEvent extends SensitiveInfoOperationEvent {
+    type: "sensitive_info_operation";
+}
+/** SubActivity waiting for command. */
+export interface WaitingCommandXacppEvent {
+    type: "waiting_command";
+}
+/** SubActivity started. */
+export interface ActivityStartXacppEvent extends ActivityStartEvent {
+    type: "activity_start";
+}
+/** SubActivity completed. */
+export interface ActivityDoneXacppEvent {
+    type: "activity_done";
+    activityId: string;
+}
+/** SubActivity aborted. */
+export interface ActivityAbortedXacppEvent {
+    type: "activity_aborted";
+    activityId: string;
+    reason: string;
+}
+/** Tool call started. */
+export interface ToolUseXacppEvent extends ToolUseEvent {
+    type: "tool_use";
+}
+/** Tool call completed. */
+export interface ToolResultXacppEvent extends ToolResultEvent {
+    type: "tool_result";
+}
+/** Security alert. */
+export interface SecurityAlertXacppEvent extends SecurityAlertEvent {
+    type: "security_alert";
+}
+/** File upload event. */
+export type UploadXacppEvent = UploadEvent & {
+    type: "upload";
+};
+/** ReAct loop single iteration completed. */
+export interface PairCompleteXacppEvent {
+    type: "pair_complete";
+    contextWindow: number;
+    tokenUsage: TokenUsage;
+}
+/** The sole terminal signal for an invoke. */
+export interface CompleteXacppEvent {
+    type: "complete";
+    assistantReply: ContentPart[];
+}
+/** ACPP protocol event union type. */
+export type XacppEvent = ContentDeltaXacppEvent | ContentPartXacppEvent | ThinkXacppEvent | InfoXacppEvent | WarnXacppEvent | ErrorXacppEvent | ActionRequestXacppEvent | NotifyXacppEvent | QuestionXacppEvent | SensitiveInfoOperationXacppEvent | WaitingCommandXacppEvent | ActivityStartXacppEvent | ActivityDoneXacppEvent | ActivityAbortedXacppEvent | ToolUseXacppEvent | ToolResultXacppEvent | SecurityAlertXacppEvent | UploadXacppEvent | PairCompleteXacppEvent | CompleteXacppEvent;

package/dist/esm/handler.d.ts

@@ -0,0 +1,41 @@
+/**
+ * XACPP Handler type definitions.
+ *
+ * This module centralizes all handler-related types:
+ *
+ * - {@link XacppSessionHandler}: logical session handler (processes Command / Event)
+ * - {@link EstablishHandler}: peer Establish request handler
+ */
+import type { XacppTransport } from "./transport";
+import type { XacppCommand } from "./commands";
+import type { XacppEvent } from "./events";
+import type { XacppResponse } from "./message";
+/** XACPP Session Handler interface.
+ *
+ * Each logical session holds one implementation, processing Commands and Events from the peer.
+ */
+export interface XacppSessionHandler {
+    /** Handle Command. */
+    onCommand(command: XacppCommand): Promise<XacppResponse>;
+    /** Handle Event. */
+    onEvent(event: XacppEvent): Promise<XacppResponse>;
+}
+/** Peer Establish request handler — serve main function.
+ *
+ * Called by the responder when receiving an Establish command from the peer.
+ * The developer performs credential validation, creates and holds a Session (for subsequent proactive sends),
+ * creates a SessionHandler and returns it. Returning reject denies the handshake.
+ */
+export interface EstablishHandler {
+    /**
+     * Handle Establish request.
+     *
+     * `transport` is passed in by Peer, for use inside `onEstablish` to create `XacppSession`.
+     * Returns `{ sessionId, handler }`: sessionId identifies this session,
+     * handler processes inbound Command/Event for this session.
+     */
+    onEstablish(transport: XacppTransport, credentials: string | null): Promise<{
+        sessionId: string;
+        handler: XacppSessionHandler;
+    }>;
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,10 @@
+export type { XacppCommand } from "./commands";
+export * from "./events";
+export { XacppError } from "./message";
+export type { XacppRequest, XacppResponse, XacppEnvelope } from "./message";
+export { XacppPeer, PeerState } from "./peer";
+export { XacppSession } from "./session";
+export { SocketTransport } from "./socket-transport";
+export { StdioTransport } from "./stdio-transport";
+export type { XacppTransport, RequestHandler } from "./transport";
+export type { XacppSessionHandler, EstablishHandler } from "./handler";

package/dist/esm/index.mjs

@@ -0,0 +1,467 @@
+import * as __rspack_external_node_net_0373943e from "node:net";
+import * as __rspack_external_node_readline_91c31510 from "node:readline";
+class XacppError extends Error {
+    code;
+    constructor(code, message){
+        super(message);
+        this.name = "XacppError";
+        this.code = code;
+    }
+    static notConnected() {
+        return new XacppError("not_connected", "not connected");
+    }
+    static alreadyConnected() {
+        return new XacppError("already_connected", "already connected");
+    }
+    static closed() {
+        return new XacppError("closed", "connection closed");
+    }
+    static noHandler() {
+        return new XacppError("no_handler", "no handler registered");
+    }
+    static internal(message) {
+        return new XacppError("internal_error", `internal error: ${message}`);
+    }
+    static application(code, message) {
+        return new XacppError(code, message);
+    }
+    static invalidRequest(message) {
+        return new XacppError("invalid_request", `invalid request: ${message}`);
+    }
+    static establishReject(reason) {
+        return new XacppError("establish_rejected", `establish rejected: ${reason}`);
+    }
+}
+class XacppSession {
+    transport;
+    _sessionId;
+    _credentials;
+    constructor(transport, sessionId, credentials){
+        this.transport = transport;
+        this._sessionId = sessionId;
+        this._credentials = credentials;
+    }
+    get sessionId() {
+        return this._sessionId;
+    }
+    get credentials() {
+        return this._credentials;
+    }
+    async requestCommand(command) {
+        return this.transport.send(this._sessionId, {
+            kind: "command",
+            payload: command
+        });
+    }
+    async requestEvent(event) {
+        return this.transport.send(this._sessionId, {
+            kind: "event",
+            payload: event
+        });
+    }
+}
+var peer_PeerState = /*#__PURE__*/ function(PeerState) {
+    PeerState["Disconnected"] = "disconnected";
+    PeerState["Connected"] = "connected";
+    return PeerState;
+}({});
+class XacppPeer {
+    transport;
+    _state = "disconnected";
+    sessions = new Map();
+    establishHandler;
+    constructor(transport, establishHandler){
+        this.transport = transport;
+        this.establishHandler = establishHandler;
+    }
+    get state() {
+        return this._state;
+    }
+    async connect() {
+        const sessions = this.sessions;
+        const establishHandler = this.establishHandler;
+        const transport = this.transport;
+        transport.onRequest((sessionId, payload)=>Promise.resolve().then(async ()=>{
+                if (null === sessionId) {
+                    if ("command" === payload.kind && "object" == typeof payload.payload && "establish" in payload.payload) {
+                        const credentials = payload.payload.establish.credentials;
+                        const result = await establishHandler.onEstablish(transport, credentials);
+                        sessions.set(result.sessionId, result.handler);
+                        return {
+                            kind: "established",
+                            sessionId: result.sessionId
+                        };
+                    }
+                    throw XacppError.invalidRequest("missing session_id");
+                }
+                const handler = sessions.get(sessionId);
+                if (!handler) throw XacppError.internal(`unknown session: ${sessionId}`);
+                if ("command" === payload.kind) return handler.onCommand(payload.payload);
+                return handler.onEvent(payload.payload);
+            }));
+        await this.transport.connect();
+        if ("disconnected" === this._state) this._state = "connected";
+    }
+    async establish(credentials, handler) {
+        const response = await this.transport.send(null, {
+            kind: "command",
+            payload: {
+                establish: {
+                    credentials
+                }
+            }
+        });
+        if ("established" === response.kind) {
+            this.sessions.set(response.sessionId, handler);
+            return new XacppSession(this.transport, response.sessionId, response.credentials ?? null);
+        }
+        if ("establish_reject" === response.kind) throw XacppError.establishReject(response.reason);
+        if ("error" === response.kind) throw XacppError.application(response.code, response.message);
+        throw XacppError.internal(`unexpected response to establish: ${JSON.stringify(response)}`);
+    }
+    async disconnect() {
+        await this.transport.disconnect();
+        this._state = "disconnected";
+        this.sessions.clear();
+    }
+    async requestCommand(sessionId, command) {
+        return this.transport.send(sessionId, {
+            kind: "command",
+            payload: command
+        });
+    }
+    async requestEvent(sessionId, event) {
+        return this.transport.send(sessionId, {
+            kind: "event",
+            payload: event
+        });
+    }
+}
+class SocketTransport {
+    socket = null;
+    handler = null;
+    pending = new Map();
+    nextId = 1;
+    _connected = false;
+    _exhausted = false;
+    writeQueue = Promise.resolve();
+    inflight = new Set();
+    port;
+    host;
+    rl = null;
+    static connectTo(port, host) {
+        const t = new SocketTransport();
+        t.port = port;
+        t.host = host ?? "127.0.0.1";
+        return t;
+    }
+    constructor(socket){
+        if (socket) this.socket = socket;
+    }
+    async connect() {
+        if (this._exhausted || this._connected) throw XacppError.alreadyConnected();
+        if (!this.socket) {
+            if (void 0 === this.port) throw XacppError.alreadyConnected();
+            this.socket = new __rspack_external_node_net_0373943e.Socket();
+            await new Promise((resolve, reject)=>{
+                const sock = this.socket;
+                const onError = (err)=>{
+                    cleanup();
+                    reject(new Error(`connect failed: ${err.message}`));
+                };
+                const onConnect = ()=>{
+                    cleanup();
+                    resolve();
+                };
+                const cleanup = ()=>{
+                    sock.removeListener("error", onError);
+                    sock.removeListener("connect", onConnect);
+                };
+                sock.once("error", onError);
+                sock.once("connect", onConnect);
+                sock.connect(this.port, this.host, ()=>{});
+            });
+        }
+        const sock = this.socket;
+        this.rl = __rspack_external_node_readline_91c31510.createInterface({
+            input: sock
+        });
+        this.rl.on("line", (line)=>this.onFrame(line));
+        this.rl.on("close", ()=>{
+            console.info("[xacpp:socket] accept loop exited");
+            this.cleanup();
+        });
+        this._connected = true;
+        console.debug("[xacpp:socket] connected");
+    }
+    async disconnect() {
+        this._exhausted = true;
+        this._connected = false;
+        for (const controller of this.inflight)controller.abort();
+        this.inflight.clear();
+        if (this.rl) {
+            this.rl.close();
+            this.rl = null;
+        }
+        if (this.socket) {
+            this.socket.destroy();
+            this.socket = null;
+        }
+        this.writeQueue = Promise.resolve();
+        this.rejectAllPending();
+        console.debug("[xacpp:socket] disconnected");
+    }
+    async send(sessionId, payload) {
+        if (!this._connected || !this.socket) throw XacppError.notConnected();
+        const id = `r${this.nextId++}`;
+        return new Promise((resolve, reject)=>{
+            this.pending.set(id, {
+                resolve,
+                reject
+            });
+            const envelope = {
+                type: "request",
+                id,
+                ...null != sessionId ? {
+                    session_id: sessionId
+                } : {},
+                payload
+            };
+            this.writeEnvelope(envelope).catch(()=>{
+                this.pending.delete(id);
+                reject(XacppError.closed());
+            });
+        });
+    }
+    onRequest(handler) {
+        if (this._connected) throw XacppError.alreadyConnected();
+        this.handler = handler;
+    }
+    async onFrame(line) {
+        let envelope;
+        try {
+            envelope = JSON.parse(line);
+        } catch  {
+            console.warn("[xacpp:socket] failed to parse frame: %s", line);
+            return;
+        }
+        if ("request" === envelope.type) this.dispatchRequest(envelope);
+        else if ("response" === envelope.type) {
+            const pending = this.pending.get(envelope.id);
+            if (pending) {
+                this.pending.delete(envelope.id);
+                pending.resolve(envelope.payload);
+            } else console.warn("[xacpp:socket] received response for unknown request %s", envelope.id);
+        }
+    }
+    dispatchRequest(envelope) {
+        if (!this.handler) return void this.writeEnvelope({
+            type: "response",
+            id: envelope.id,
+            ...null != envelope.session_id ? {
+                session_id: envelope.session_id
+            } : {},
+            payload: {
+                kind: "error",
+                code: "no_handler",
+                message: "no handler registered"
+            }
+        }).catch(()=>{});
+        const controller = new AbortController();
+        this.inflight.add(controller);
+        const sessionId = envelope.session_id ?? null;
+        const handler = this.handler;
+        handler(sessionId, envelope.payload).then((responsePayload)=>{
+            if (controller.signal.aborted) return;
+            return this.writeEnvelope({
+                type: "response",
+                id: envelope.id,
+                ...null != envelope.session_id ? {
+                    session_id: envelope.session_id
+                } : {},
+                payload: responsePayload
+            });
+        }).catch((e)=>{
+            if (controller.signal.aborted) return;
+            const err = e instanceof XacppError ? e : XacppError.internal(e instanceof Error ? e.message : String(e));
+            console.error("[xacpp:socket] handler error for request %s: %s", envelope.id, err.message);
+            return this.writeEnvelope({
+                type: "response",
+                id: envelope.id,
+                ...null != envelope.session_id ? {
+                    session_id: envelope.session_id
+                } : {},
+                payload: {
+                    kind: "error",
+                    code: err.code,
+                    message: err.message
+                }
+            });
+        }).finally(()=>{
+            this.inflight.delete(controller);
+        });
+    }
+    writeEnvelope(envelope) {
+        if (!this.socket) return Promise.reject(XacppError.closed());
+        const json = JSON.stringify(envelope) + "\n";
+        const sock = this.socket;
+        let resolveOp;
+        let rejectOp;
+        const opPromise = new Promise((resolve, reject)=>{
+            resolveOp = resolve;
+            rejectOp = reject;
+        });
+        this.writeQueue = this.writeQueue.then(()=>new Promise((chainResolve)=>{
+                sock.write(json, (err)=>{
+                    if (err) rejectOp(XacppError.closed());
+                    else resolveOp();
+                    chainResolve();
+                });
+            }), ()=>{});
+        return opPromise;
+    }
+    rejectAllPending() {
+        const err = XacppError.closed();
+        for (const [, p] of this.pending)p.reject(err);
+        this.pending.clear();
+    }
+    cleanup() {
+        this._connected = false;
+        this.rejectAllPending();
+    }
+}
+class StdioTransport {
+    writer;
+    reader;
+    rl = null;
+    _connected = false;
+    _exhausted = false;
+    requestHandler = null;
+    pending = new Map();
+    nextId = 1;
+    constructor(writer, reader){
+        this.writer = writer;
+        this.reader = reader;
+    }
+    genId() {
+        return `r${this.nextId++}`;
+    }
+    async connect() {
+        if (this._exhausted) throw XacppError.alreadyConnected();
+        if (this._connected) throw XacppError.alreadyConnected();
+        if (!this.writer || !this.reader) throw XacppError.alreadyConnected();
+        this.rl = __rspack_external_node_readline_91c31510.createInterface({
+            input: this.reader
+        });
+        this.rl.on("line", (line)=>{
+            this.onFrame(line);
+        });
+        this.rl.on("close", ()=>{
+            console.info("[xacpp:stdio] accept loop exited");
+            this.cleanup();
+        });
+        this._connected = true;
+        console.debug("[xacpp:stdio] connected");
+    }
+    async disconnect() {
+        if (this.rl) {
+            this.rl.close();
+            this.rl = null;
+        }
+        if (this.writer) {
+            this.writer.end();
+            this.writer = null;
+        }
+        this.reader = null;
+        this.cleanup();
+        this._exhausted = true;
+        console.debug("[xacpp:stdio] disconnected");
+    }
+    async send(sessionId, payload) {
+        if (!this._connected || !this.writer) throw XacppError.notConnected();
+        const id = this.genId();
+        return new Promise((resolve, reject)=>{
+            this.pending.set(id, {
+                resolve,
+                reject
+            });
+            const envelope = {
+                type: "request",
+                id,
+                ...null != sessionId ? {
+                    session_id: sessionId
+                } : {},
+                payload
+            };
+            const json = JSON.stringify(envelope) + "\n";
+            this.writer.write(json, (err)=>{
+                if (err) {
+                    this.pending.delete(id);
+                    reject(XacppError.closed());
+                }
+            });
+        });
+    }
+    onRequest(handler) {
+        if (this._connected) throw XacppError.alreadyConnected();
+        this.requestHandler = handler;
+    }
+    async onFrame(line) {
+        let envelope;
+        try {
+            envelope = JSON.parse(line);
+        } catch  {
+            console.warn("[xacpp:stdio] failed to parse frame: %s", line);
+            return;
+        }
+        if ("request" === envelope.type) await this.handleRequest(envelope.id, envelope.session_id ?? null, envelope.payload);
+        else if ("response" === envelope.type) this.handleResponse(envelope.id, envelope.payload);
+    }
+    async handleRequest(id, sessionId, payload) {
+        let responsePayload;
+        try {
+            if (!this.requestHandler) throw XacppError.noHandler();
+            responsePayload = await this.requestHandler(sessionId, payload);
+        } catch (e) {
+            const err = e instanceof XacppError ? e : XacppError.internal(e instanceof Error ? e.message : String(e));
+            console.error("[xacpp:stdio] handler error for request %s: %s", id, err.message);
+            responsePayload = {
+                kind: "error",
+                code: err.code,
+                message: err.message
+            };
+        }
+        const response = {
+            type: "response",
+            id,
+            ...null != sessionId ? {
+                session_id: sessionId
+            } : {},
+            payload: responsePayload
+        };
+        const ok = this.writeEnvelope(response);
+        if (!ok) console.warn("[xacpp:stdio] failed to send response for request %s", id);
+    }
+    handleResponse(id, payload) {
+        const pending = this.pending.get(id);
+        if (pending) {
+            this.pending.delete(id);
+            pending.resolve(payload);
+        } else console.warn("[xacpp:stdio] received response for unknown request %s", id);
+    }
+    writeEnvelope(envelope) {
+        if (!this.writer) return false;
+        const json = JSON.stringify(envelope) + "\n";
+        return this.writer.write(json);
+    }
+    cleanup() {
+        this._connected = false;
+        const err = XacppError.closed();
+        for (const [id, pending] of this.pending){
+            console.warn("[xacpp:stdio] rejecting pending request %s: %s", id, err.message);
+            pending.reject(err);
+        }
+        this.pending.clear();
+    }
+}
+export { SocketTransport, StdioTransport, XacppError, XacppPeer, XacppSession, peer_PeerState as PeerState };