xacpp 0.1.0

package/dist/cjs/index.js

@@ -0,0 +1,516 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    PeerState: ()=>peer_PeerState,
+    SocketTransport: ()=>SocketTransport,
+    StdioTransport: ()=>StdioTransport,
+    XacppError: ()=>XacppError,
+    XacppPeer: ()=>XacppPeer,
+    XacppSession: ()=>XacppSession
+});
+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
+        });
+    }
+}
+const external_node_net_namespaceObject = require("node:net");
+const external_node_readline_namespaceObject = require("node:readline");
+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 external_node_net_namespaceObject.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 = external_node_readline_namespaceObject.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 = external_node_readline_namespaceObject.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();
+    }
+}
+exports.PeerState = __webpack_exports__.PeerState;
+exports.SocketTransport = __webpack_exports__.SocketTransport;
+exports.StdioTransport = __webpack_exports__.StdioTransport;
+exports.XacppError = __webpack_exports__.XacppError;
+exports.XacppPeer = __webpack_exports__.XacppPeer;
+exports.XacppSession = __webpack_exports__.XacppSession;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "PeerState",
+    "SocketTransport",
+    "StdioTransport",
+    "XacppError",
+    "XacppPeer",
+    "XacppSession"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/esm/commands/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * XACPP protocol command types.
+ *
+ * Commands are transmitted via transport, driving the interaction flow between the initiator and the peer.
+ *
+ * Establish replaces the legacy Paring/Authenticate, unifying handshake and session establishment.
+ */
+/** XACPP protocol command. */
+export type XacppCommand = 
+/** Establish logical session. */
+{
+    establish: {
+        credentials: string | null;
+    };
+}
+/** Create a new Activity session. */
+ | "new_activity"
+/** Invoke an existing Activity to perform an operation. */
+ | "invoke_activity"
+/** Compact Activity (reclaim resources / generate snapshot summary). */
+ | "compact_activity"
+/** Cancel Activity. */
+ | "cancel_activity";

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

@@ -0,0 +1,40 @@
+/** 多模态内容基础类型。 */
+/** 文件引用（协议级简化版）。 */
+export interface FileRef {
+    remoteUrl: string;
+    localUri: string;
+    mimeType: string;
+    sizeBytes: number;
+}
+export interface TextPart {
+    type: "text";
+    text: string;
+    partId?: string;
+}
+export interface ImagePart {
+    type: "image";
+    source: FileRef;
+    detail?: string;
+    width?: number;
+    height?: number;
+    partId?: string;
+}
+export interface AudioPart {
+    type: "audio";
+    source: FileRef;
+    sampleRate?: number;
+    channels?: number;
+    durationMs?: number;
+    partId?: string;
+}
+export interface VideoPart {
+    type: "video";
+    source: FileRef;
+    durationMs?: number;
+    fps?: number;
+    width?: number;
+    height?: number;
+    partId?: string;
+}
+/** 统一多模态内容分片。 */
+export type ContentPart = TextPart | ImagePart | AudioPart | VideoPart;

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

@@ -0,0 +1,10 @@
+/**
+ * ACPP event types.
+ *
+ * Standardized event stream between the initiator and the peer.
+ */
+export * from "./content";
+export * from "./interaction";
+export * from "./payload";
+export * from "./upload";
+export type { XacppEvent } from "./xacpp_event";

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

@@ -0,0 +1,88 @@
+/**
+ * 交互事件载荷（请求-响应模式）。
+ *
+ * 协议层不持有通道，通过 requestId 进行请求-响应关联，
+ * 响应方通过 transport 发送对应的 Response 消息。
+ */
+import type { AlertLevel } from "./payload";
+/** 工具调用授权响应。 */
+export type ActionResponse = {
+    type: "approve";
+} | {
+    type: "approve_always";
+} | {
+    type: "reject";
+    reason: string;
+};
+/** 工具调用授权请求事件载荷。 */
+export interface ActionRequestEvent {
+    requestId: string;
+    toolName: string;
+    arguments: string;
+    actionId: string;
+    description: string;
+    alert: AlertLevel;
+}
+/** 用户通知事件载荷（单向推送，不阻塞等待回复）。 */
+export interface NotifyEvent {
+    requestId: string;
+    message: string;
+}
+/** 用户提问响应。 */
+export type QuestionResponse = {
+    type: "answer";
+    content: string;
+} | {
+    type: "skip";
+    reason?: string;
+};
+/** 用户提问事件载荷。 */
+export interface QuestionEvent {
+    requestId: string;
+    question: string;
+    options: string[];
+}
+/** 敏感信息类型。 */
+export type SensitiveInfoType = "secret" | "env_var";
+/** 敏感信息条目（脱敏展示）。 */
+export interface SensitiveInfoItem {
+    id?: string;
+    key: string;
+    displayText: string;
+    hint: string;
+    siType: SensitiveInfoType;
+}
+/** 敏感信息操作类型。 */
+export type SensitiveInfoOperation = {
+    type: "collect";
+    items: SensitiveInfoItem[];
+} | {
+    type: "delete";
+    items: SensitiveInfoItem[];
+};
+/** 单个敏感信息的操作结果。 */
+export type SensitiveInfoResult = {
+    type: "provided";
+    key: string;
+    value: string;
+} | {
+    type: "collect_skipped";
+    key: string;
+    reason?: string;
+} | {
+    type: "deleted";
+    id: string;
+} | {
+    type: "delete_rejected";
+    id: string;
+    reason?: string;
+};
+/** 敏感信息操作响应。 */
+export interface SensitiveInfoOperationResponse {
+    results: SensitiveInfoResult[];
+}
+/** 敏感信息操作请求事件载荷。 */
+export interface SensitiveInfoOperationEvent {
+    requestId: string;
+    operation: SensitiveInfoOperation;
+}