@pllla/openclaw-plugin 0.1.0

package/dist/accounts.js

@@ -0,0 +1,66 @@
+/**
+ * Account config — `channels.pllla` normalized into an account map.
+ *
+ * One pairing = one rt- key = one aiUserId = one socket lane. Attaching N
+ * PLLLA agents to a single gateway therefore means N accounts, each with its
+ * own lane and its own stored state (docs/agent/EXTERNAL_RUNTIME.md §6.3).
+ *
+ * `accounts` is the source of truth. The flat Phase 1 fields
+ * (`channels.pllla.{serverOrigin,pairingToken,runtimeLabel}`) are read as the
+ * `default` account so existing installs keep working unchanged.
+ */
+export const DEFAULT_ACCOUNT_ID = "default";
+// accountId 는 상태 파일 이름(`accounts/<accountId>.json`)이 된다 — 경로 구분자·
+// 선행 점을 막아 상태 디렉토리 밖으로 새지 않게 한다. 커넥터 기본값
+// `agent-` + 8 hex 와 `default` 가 통과해야 한다.
+const ACCOUNT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+export function isValidAccountId(accountId) {
+    return ACCOUNT_ID_PATTERN.test(accountId);
+}
+export function assertValidAccountId(accountId) {
+    if (!isValidAccountId(accountId)) {
+        throw new Error(`Invalid PLLLA account id "${accountId}" — use letters, digits, ".", "_" or "-" (max 64 chars, must start with a letter or digit).`);
+    }
+}
+function normalizeOrigin(value) {
+    return typeof value === "string" ? value.trim().replace(/\/+$/, "") : "";
+}
+function normalizeOptional(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+}
+function toAccount(raw) {
+    return {
+        serverOrigin: normalizeOrigin(raw?.serverOrigin),
+        pairingToken: normalizeOptional(raw?.pairingToken),
+        runtimeLabel: normalizeOptional(raw?.runtimeLabel),
+    };
+}
+/**
+ * Every configured account, keyed by accountId. Entries are kept even when
+ * `serverOrigin` is missing or the id is unsafe — the caller decides what to
+ * report, and silently dropping an account is exactly the defect §6.3 fixes.
+ */
+export function parseAccounts(config) {
+    const accounts = new Map();
+    const rawAccounts = config?.accounts;
+    if (rawAccounts && typeof rawAccounts === "object") {
+        for (const [accountId, raw] of Object.entries(rawAccounts)) {
+            accounts.set(accountId, toAccount(raw));
+        }
+    }
+    // Phase 1 평면 설정 → `default`. 맵에 `default` 가 이미 있으면 맵이 정본이라
+    // 평면 필드는 무시한다(둘을 합치면 어느 토큰이 소비될지 예측할 수 없다).
+    const flat = toAccount(config);
+    if (!accounts.has(DEFAULT_ACCOUNT_ID) &&
+        (flat.serverOrigin || flat.pairingToken)) {
+        accounts.set(DEFAULT_ACCOUNT_ID, flat);
+    }
+    return accounts;
+}
+/** `accounts` keys, plus `default` when the flat Phase 1 fields are set. */
+export function listAccountIds(config) {
+    return [...parseAccounts(config).keys()];
+}

package/dist/bridges.js

@@ -0,0 +1,110 @@
+/**
+ * PLLLA bridges — one lane per configured account (accounts.ts).
+ *
+ * Boot sequence (gateway start), per account:
+ *   1. Read channel config — `channels.pllla.accounts.<id>`, or the flat
+ *      Phase 1 fields as the `default` account.
+ *   2. Stored bridge state for the account → reuse it. None, but a
+ *      `pairingToken` → consume it (pairing.ts) and persist (stateStore.ts).
+ *      Neither → skip that account and say so.
+ *   3. Open one PLLLA lane per account (lane.ts) — socket contract straight
+ *      from the pairing response — and route each task into an OpenClaw
+ *      agent turn under `pllla:<accountId>:<chatId>`.
+ *
+ * One account's failure never blocks another's lane: each account is
+ * resolved inside its own try/catch and only ever touches its own state
+ * file (docs/agent/EXTERNAL_RUNTIME.md §6.3).
+ *
+ * SDK-free on purpose so it stays unit-testable; index.ts adapts it to the
+ * OpenClaw plugin SDK.
+ */
+import { consumePairingToken } from "./pairing.js";
+import { PlllaLane } from "./lane.js";
+import { loadBridgeState, saveBridgeState, } from "./stateStore.js";
+import { parseAccounts, } from "./accounts.js";
+export function buildPersonaPrompt(identity) {
+    return [
+        identity.name ? `You are ${identity.name}, a PLLLA agent.` : "",
+        identity.bio,
+        identity.systemPrompt,
+    ]
+        .filter(Boolean)
+        .join("\n\n");
+}
+/**
+ * Stored state wins; a pairing token is consumed only when there is no usable
+ * state for this account. Returns null (after logging why) when the account
+ * cannot be opened — never throws for "not configured", only for real errors.
+ */
+async function resolveAccountState(accountId, account, log) {
+    const stored = loadBridgeState(accountId);
+    if (stored && stored.serverOrigin === account.serverOrigin) {
+        if (account.pairingToken) {
+            log("Stored pairing found — ignoring channels.pllla pairingToken.");
+        }
+        return stored;
+    }
+    if (!account.serverOrigin) {
+        log("Skipped — serverOrigin is missing.");
+        return null;
+    }
+    if (!account.pairingToken) {
+        log(stored
+            ? `Skipped — stored pairing is for ${stored.serverOrigin} but config says ${account.serverOrigin}; run \`npx pllla-connect …\` for a fresh token.`
+            : "Skipped — no stored pairing and no pairingToken; run `npx pllla-connect …` for a fresh token.");
+        return null;
+    }
+    log("Consuming PLLLA pairing token…");
+    const pair = await consumePairingToken({
+        serverOrigin: account.serverOrigin,
+        pairingToken: account.pairingToken,
+        runtimeLabel: account.runtimeLabel || "OpenClaw",
+    });
+    const state = {
+        serverOrigin: account.serverOrigin,
+        pair,
+        savedAt: new Date().toISOString(),
+    };
+    saveBridgeState(accountId, state);
+    log(`Paired as @${pair.aiUser.username} (${pair.externalRuntime?.label ?? "external runtime"}).`);
+    return state;
+}
+export async function createPlllaBridges(params) {
+    const { config, runTurn, log } = params;
+    const accounts = parseAccounts(config);
+    const lanes = new Map();
+    if (accounts.size === 0) {
+        log("No PLLLA accounts configured — set channels.pllla.accounts.<id>.{serverOrigin,pairingToken} (`npx pllla-connect …` does this).");
+        return { lanes, stop: () => undefined };
+    }
+    await Promise.all([...accounts].map(async ([accountId, account]) => {
+        const accountLog = (line) => log(`[${accountId}] ${line}`);
+        // 계정별 격리 — 한 계정의 페어링 실패·상태 오류가 다른 계정의 레인을
+        // 막지 않는다. 각 계정은 자기 상태 파일만 읽고 쓴다.
+        try {
+            const state = await resolveAccountState(accountId, account, accountLog);
+            if (!state)
+                return;
+            const lane = new PlllaLane({
+                accountId,
+                socketContract: state.pair.socket,
+                aiUserId: state.pair.aiUser.id,
+                systemPrompt: buildPersonaPrompt(state.pair.identity),
+                runTurn,
+                log: accountLog,
+            });
+            lane.start();
+            lanes.set(accountId, lane);
+        }
+        catch (error) {
+            accountLog(`Failed to open lane: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }));
+    return {
+        lanes,
+        stop: () => {
+            for (const lane of lanes.values())
+                lane.stop();
+        },
+    };
+}

package/dist/index.js

@@ -0,0 +1,215 @@
+/**
+ * OpenClaw channel plugin entry — PLLLA as an OpenClaw channel.
+ *
+ * Pinned to the real plugin SDK (OpenClaw 2026.8.2, read from the installed
+ * `dist/*.d.ts` on 2026-09-02 — docs/agent/EXTERNAL_RUNTIME.md §6):
+ *
+ *   - `defineChannelPluginEntry` (plugin-sdk/core) is the canonical entry.
+ *     OpenClaw calls its `register(api)` at gateway start.
+ *   - The channel itself is `createChatChannelPlugin` around a
+ *     `createChannelPluginBase` — account listing/resolution comes from
+ *     accounts.ts, so `openclaw config set channels.pllla.accounts.<id>.…`
+ *     validates against a registered channel id (the "unknown channel id:
+ *     pllla" failure seen on a real machine was exactly this registration
+ *     missing).
+ *   - The long-lived socket lanes live in a plugin **service**
+ *     (`api.registerService`) — the SDK's home for background ingress — not
+ *     in a request handler.
+ *   - Each PLLLA task becomes one agent turn through
+ *     `api.runtime.agent.runCommandFromIngress` ("admit a turn for this exact
+ *     trusted channel plugin"), which returns the reply `payloads` directly —
+ *     no outbound correlation needed.
+ *
+ * Persona (from the pairing exchange) is prepended once per OpenClaw session
+ * as a bracketed preamble — interim. The proper home is a per-account OpenClaw
+ * agent identity; tracked as follow-up.
+ */
+import { defineChannelPluginEntry, } from "openclaw/plugin-sdk/core";
+import { createChannelPluginBase, createChatChannelPlugin, } from "openclaw/plugin-sdk/channel-core";
+import { DEFAULT_ACCOUNT_ID, listAccountIds, parseAccounts, } from "./accounts.js";
+import { createPlllaBridges } from "./bridges.js";
+export { listAccountIds, parseAccounts } from "./accounts.js";
+export { createPlllaBridges } from "./bridges.js";
+const CHANNEL_ID = "pllla";
+const SERVICE_ID = "pllla-lanes";
+function readChannelConfig(cfg) {
+    const section = cfg.channels?.[CHANNEL_ID];
+    return section && typeof section === "object"
+        ? section
+        : undefined;
+}
+function resolveAccount(cfg, accountId) {
+    const id = accountId || DEFAULT_ACCOUNT_ID;
+    const account = parseAccounts(readChannelConfig(cfg)).get(id);
+    return {
+        accountId: id,
+        serverOrigin: account?.serverOrigin ?? "",
+        pairingToken: account?.pairingToken,
+        runtimeLabel: account?.runtimeLabel,
+    };
+}
+/** `pllla:<accountId>:<chatId>` → accountId (lane.ts buildSessionKey). */
+export function accountIdFromSessionKey(sessionKey) {
+    const parts = sessionKey.split(":");
+    return parts.length >= 3 && parts[0] === CHANNEL_ID
+        ? parts[1]
+        : DEFAULT_ACCOUNT_ID;
+}
+/** The message OpenClaw should see for this task — last user turn. */
+export function pickTurnMessage(input) {
+    for (let index = input.messages.length - 1; index >= 0; index -= 1) {
+        const message = input.messages[index];
+        if (message.role === "user" && message.content.trim()) {
+            return message.content;
+        }
+    }
+    return input.messages.map((message) => message.content).join("\n\n");
+}
+/**
+ * Persona goes in front of the first turn of each OpenClaw session only —
+ * OpenClaw keeps the session transcript itself, so repeating it every turn
+ * would just bloat context.
+ */
+export function buildTurnMessage(input, seenSessions) {
+    const message = pickTurnMessage(input);
+    if (seenSessions.has(input.sessionId) || !input.systemPrompt.trim()) {
+        return message;
+    }
+    seenSessions.add(input.sessionId);
+    return `[PLLLA agent persona — follow throughout this conversation]\n${input.systemPrompt.trim()}\n[end persona]\n\n${message}`;
+}
+/** Join reply payloads into the single text PLLLA's `agent:response` carries. */
+export function joinPayloadText(payloads) {
+    return payloads
+        .map((payload) => (payload.text ?? "").trim())
+        .filter(Boolean)
+        .join("\n\n");
+}
+function createRunTurn(api) {
+    const seenSessions = new Set();
+    const runtimeEnv = {
+        log: (...args) => api.logger.info(...args),
+        error: (...args) => api.logger.error(...args),
+        // 플러그인 안에서 프로세스를 끝내지 않는다 — 게이트웨이의 것이다.
+        exit: () => undefined,
+    };
+    return async (input) => {
+        const result = await api.runtime.agent.runCommandFromIngress({
+            message: buildTurnMessage(input, seenSessions),
+            sessionKey: input.sessionId,
+            channel: CHANNEL_ID,
+            messageChannel: CHANNEL_ID,
+            accountId: accountIdFromSessionKey(input.sessionId),
+            // 응답은 우리가 PLLLA 소켓으로 나른다 — OpenClaw 배달 경로는 끈다.
+            deliver: false,
+            json: true,
+            allowModelOverride: false,
+        }, runtimeEnv);
+        return joinPayloadText(result.payloads ?? []);
+    };
+}
+const channelBase = createChannelPluginBase({
+    id: CHANNEL_ID,
+    meta: {
+        label: "PLLLA",
+        selectionLabel: "PLLLA",
+        docsPath: "/channels/pllla",
+        blurb: "Reply as your PLLLA agent — paired with `npx pllla-connect`.",
+    },
+    config: {
+        listAccountIds: (cfg) => listAccountIds(readChannelConfig(cfg)),
+        resolveAccount,
+        inspectAccount: (cfg, accountId) => {
+            const account = resolveAccount(cfg, accountId);
+            return {
+                accountId: account.accountId,
+                enabled: true,
+                configured: Boolean(account.serverOrigin),
+            };
+        },
+    },
+    setup: {
+        // `openclaw config set channels.pllla.accounts.<id>.<key>` 가 쓰는 병합 —
+        // 그 계정의 키만 덮고 다른 계정은 건드리지 않는다 (§6.3).
+        applyAccountConfig: ({ cfg, accountId, input }) => {
+            const id = accountId || DEFAULT_ACCOUNT_ID;
+            const section = readChannelConfig(cfg) ?? {};
+            const accounts = { ...(section.accounts ?? {}) };
+            accounts[id] = { ...(accounts[id] ?? {}), ...input };
+            return {
+                ...cfg,
+                channels: {
+                    ...(cfg.channels ?? {}),
+                    [CHANNEL_ID]: { ...section, accounts },
+                },
+            };
+        },
+    },
+});
+let bridges = null;
+/**
+ * OpenClaw's own messaging tool ("send this to pllla") lands here. The lane
+ * for the account forwards it as `agent:send_message` on the PLLLA socket.
+ */
+function sendTextToPllla(ctx) {
+    const accountId = ctx.accountId || DEFAULT_ACCOUNT_ID;
+    const chatId = ctx.to ?? ctx.target;
+    const text = ctx.text ?? "";
+    const lane = bridges?.lanes.get(accountId);
+    if (!lane || !chatId || !text)
+        return {};
+    const sent = lane.sendChatMessage(String(chatId), text);
+    return sent ? { messageId: `pllla:${chatId}:${Date.now()}` } : {};
+}
+const plllaChannelPlugin = createChatChannelPlugin({
+    base: channelBase,
+    security: {
+        dm: {
+            channelKey: CHANNEL_ID,
+            // PLLLA 쪽 권한(친구=대화 자격·그랜트=작업 자격)이 정본이다 — 채널 자체는
+            // 페어링된 계정 소켓으로만 말이 들어오므로 allowlist 로 잠근다.
+            resolvePolicy: () => "allowlist",
+            resolveAllowFrom: () => [],
+            defaultPolicy: "allowlist",
+        },
+    },
+    threading: { topLevelReplyToMode: "reply" },
+    outbound: {
+        attachedResults: {
+            channel: CHANNEL_ID,
+            sendText: sendTextToPllla,
+        },
+    },
+});
+function registerFull(api) {
+    const log = (line) => api.logger.info(`[pllla] ${line}`);
+    const runTurn = createRunTurn(api);
+    api.registerService({
+        id: SERVICE_ID,
+        start: async (ctx) => {
+            // 상태 파일은 게이트웨이의 state dir 아래에 둔다 (stateStore.ts 는
+            // OPENCLAW_STATE_DIR 을 읽는다 — 게이트웨이가 안 넘겨준 경우만 채운다).
+            if (!process.env.OPENCLAW_STATE_DIR && ctx.stateDir) {
+                process.env.OPENCLAW_STATE_DIR = ctx.stateDir;
+            }
+            bridges = await createPlllaBridges({
+                config: readChannelConfig(ctx.config),
+                runTurn,
+                log,
+            });
+            log(`${bridges.lanes.size} PLLLA lane(s) open.`);
+        },
+        stop: async () => {
+            bridges?.stop();
+            bridges = null;
+        },
+    });
+}
+const entry = defineChannelPluginEntry({
+    id: CHANNEL_ID,
+    name: "PLLLA",
+    description: "Reply as a PLLLA agent — one socket lane per paired account, persona from the pairing exchange.",
+    plugin: plllaChannelPlugin,
+    registerFull,
+});
+export default entry;

package/dist/lane.js

@@ -0,0 +1,158 @@
+/**
+ * PLLLA agent lane — the socket side of the bridge. Follows the
+ * self-describing contract from the pairing exchange: connect with the given
+ * auth/transports, handle the task event, reply on the response event.
+ *
+ * One lane per account: the rt- key in `socketContract.auth` and `aiUserId`
+ * are that account's identity, and every session key carries the accountId
+ * so two agents on one gateway never share a runtime session.
+ *
+ * The lane knows nothing about OpenClaw: it takes an AgentTurnRunner and
+ * reports each task's outcome. The OpenClaw-facing wiring lives in index.ts.
+ */
+import { io } from "socket.io-client";
+/**
+ * `pllla:<accountId>:<chatId>` — the same chatId under two accounts is two
+ * sessions (docs/agent/EXTERNAL_RUNTIME.md §6.3).
+ */
+export function buildSessionKey(accountId, chatId) {
+    return `pllla:${accountId}:${chatId}`;
+}
+export class PlllaLane {
+    options;
+    socket = null;
+    // sessionId → 마지막 턴의 꼬리. OpenClaw 는 한 세션에 동시 턴을 허용하지 않아
+    // ("Session … already has an active turn claim"), 첫 인사 턴과 첫 태스크가 같은
+    // 채팅을 물면 충돌한다. 같은 세션의 턴을 직렬화하고, 다른 세션은 병렬로 둔다.
+    sessionTails = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    get accountId() {
+        return this.options.accountId;
+    }
+    /**
+     * Run one agent turn, serialized per sessionId. Same-session turns queue
+     * (greeting → first task → next message); different sessions run in parallel.
+     * A failed turn never wedges the queue — the next turn still runs.
+     */
+    async runTurnSerialized(input) {
+        const key = input.sessionId;
+        const prior = this.sessionTails.get(key) ?? Promise.resolve();
+        let release;
+        const gate = new Promise((resolve) => {
+            release = resolve;
+        });
+        const tail = prior.then(() => gate);
+        this.sessionTails.set(key, tail);
+        await prior.catch(() => undefined);
+        try {
+            return await this.options.runTurn(input);
+        }
+        finally {
+            release();
+            // 우리가 아직 꼬리면 정리한다 — 뒤에 다른 턴이 붙었으면 그대로 둔다.
+            if (this.sessionTails.get(key) === tail)
+                this.sessionTails.delete(key);
+        }
+    }
+    start() {
+        const { socketContract } = this.options;
+        const socket = io(socketContract.url, {
+            path: socketContract.path,
+            transports: socketContract.transports,
+            auth: socketContract.auth,
+            reconnection: true,
+        });
+        this.socket = socket;
+        socket.on("connect", () => this.options.log("PLLLA lane connected."));
+        socket.on("disconnect", (reason) => this.options.log(`PLLLA lane disconnected: ${reason}`));
+        const readyEvent = socketContract.events.runtimeReady;
+        if (readyEvent) {
+            socket.on(readyEvent, (payload) => {
+                void this.handleRuntimeReady(payload);
+            });
+        }
+        socket.on(socketContract.events.task, (payload) => {
+            void this.handleTask(payload?.task);
+        });
+    }
+    stop() {
+        this.socket?.disconnect();
+        this.socket = null;
+    }
+    /**
+     * Outbound from OpenClaw's side (its messaging tool) into a PLLLA chat —
+     * `agent:send_message` on this account's lane. Returns false when the lane
+     * is not connected or the contract has no sendMessage event.
+     */
+    sendChatMessage(chatId, content) {
+        const event = this.options.socketContract.events.sendMessage;
+        if (!event || !this.socket?.connected)
+            return false;
+        this.socket.emit(event, {
+            chatId,
+            aiUserId: this.options.aiUserId,
+            content,
+        });
+        return true;
+    }
+    emitResponse(taskId, content, failure) {
+        this.socket?.emit(this.options.socketContract.events.response, {
+            taskId,
+            aiUserId: this.options.aiUserId,
+            content,
+            ...(failure ? { failure } : {}),
+        });
+    }
+    async handleRuntimeReady(payload) {
+        if (!payload?.greeting?.shouldSend)
+            return;
+        const sendMessageEvent = this.options.socketContract.events.sendMessage;
+        const chatId = payload.greeting.chatId;
+        if (!sendMessageEvent || !chatId)
+            return;
+        try {
+            const greeting = this.options.firstGreeting ||
+                (await this.runTurnSerialized({
+                    sessionId: buildSessionKey(this.options.accountId, chatId),
+                    systemPrompt: this.options.systemPrompt,
+                    messages: [
+                        {
+                            role: "user",
+                            content: "You just came online for your owner for the first time. Send a short first greeting in your own voice.",
+                        },
+                    ],
+                }));
+            this.socket?.emit(sendMessageEvent, {
+                chatId,
+                aiUserId: this.options.aiUserId,
+                content: greeting,
+            });
+        }
+        catch (error) {
+            this.options.log(`First greeting failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    async handleTask(task) {
+        if (!task?.id)
+            return;
+        try {
+            const content = await this.runTurnSerialized({
+                sessionId: buildSessionKey(this.options.accountId, task.chatId),
+                // 서버 프롬프트(대화 맥락) 위에 페어링에서 받은 페르소나를 얹는다 —
+                // PLLLA 에이전트의 정체성이 런타임까지 그대로 이식되는 지점.
+                systemPrompt: [this.options.systemPrompt, task.systemPrompt]
+                    .filter(Boolean)
+                    .join("\n\n"),
+                messages: Array.isArray(task.messages) ? task.messages : [],
+            });
+            this.emitResponse(task.id, content);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Agent turn failed";
+            this.options.log(`Task ${task.id} failed: ${message}`);
+            this.emitResponse(task.id, "", message);
+        }
+    }
+}

package/dist/pairing.js

@@ -0,0 +1,36 @@
+/**
+ * PLLLA pairing exchange — one POST that turns a one-time pair_live_ token
+ * into everything the bridge needs: the rt- runtime key, the socket contract
+ * (self-describing: url/path/event names come from the server), and the
+ * agent's identity for persona injection (docs/agent/EXTERNAL_RUNTIME.md).
+ */
+export const SUPPORTED_CONTRACT_VERSION = 1;
+export async function consumePairingToken(params) {
+    const response = await fetch(`${params.serverOrigin}/api/user/ai-agent/pair`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            pairingToken: params.pairingToken,
+            runtimeLabel: params.runtimeLabel,
+        }),
+    });
+    const data = (await response.json().catch(() => null));
+    if (!response.ok || !data?.success) {
+        throw new Error(data?.error || `PLLLA pairing failed (HTTP ${response.status}).`);
+    }
+    if (!data.runtimeKey || !data.socket?.url || !data.socket.events?.task) {
+        throw new Error("PLLLA pairing response is missing the socket contract.");
+    }
+    // 계약 세대 검증 — 미지의 세대에서 조용히 오동작하지 않고 정직하게 실패한다.
+    if ((data.contractVersion ?? 0) !== SUPPORTED_CONTRACT_VERSION) {
+        throw new Error(`This bridge speaks PLLLA contract v${SUPPORTED_CONTRACT_VERSION}, but the server speaks v${data.contractVersion}. Update: openclaw plugins install npm:@pllla/openclaw-plugin@latest`);
+    }
+    return {
+        contractVersion: data.contractVersion ?? 0,
+        runtimeKey: data.runtimeKey,
+        aiUser: data.aiUser ?? { id: "", username: "", name: "" },
+        identity: data.identity ?? { name: "", bio: "", systemPrompt: "" },
+        externalRuntime: data.externalRuntime ?? null,
+        socket: data.socket,
+    };
+}

package/dist/stateStore.js

@@ -0,0 +1,88 @@
+/**
+ * Bridge state — the consumed pairing result (rt- runtime key + socket
+ * contract + identity) persisted across gateway restarts, one file per
+ * account:
+ *
+ *   <OPENCLAW_STATE_DIR | ~/.openclaw>/pllla/accounts/<accountId>.json
+ *
+ * Lives under the OpenClaw state dir so `openclaw uninstall` cleans it up
+ * with everything else. The pairing token itself is one-shot; after a
+ * successful exchange only this state matters.
+ *
+ * Phase 1 kept a single `pllla/bridge-state.json`. It is moved to
+ * `accounts/default.json` the first time the `default` account is loaded
+ * (docs/agent/EXTERNAL_RUNTIME.md §6.3).
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { assertValidAccountId, DEFAULT_ACCOUNT_ID } from "./accounts.js";
+const STATE_FILE_MODE = 0o600;
+export function openclawStateDir() {
+    return process.env.OPENCLAW_STATE_DIR || join(homedir(), ".openclaw");
+}
+export function bridgeStatePath(accountId) {
+    assertValidAccountId(accountId);
+    return join(openclawStateDir(), "pllla", "accounts", `${accountId}.json`);
+}
+/** Phase 1 single-account file — only read for migration. */
+export function legacyBridgeStatePath() {
+    return join(openclawStateDir(), "pllla", "bridge-state.json");
+}
+function readState(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return parsed?.pair?.runtimeKey ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function lockDown(path) {
+    // writeFileSync 의 mode 는 생성 시에만 적용된다 — 기존 파일·rename 된 파일도
+    // rt- 키가 들어 있으니 항상 0600 으로 맞춘다.
+    try {
+        chmodSync(path, STATE_FILE_MODE);
+    }
+    catch {
+        // Windows 등 chmod 미지원 — 파일 자체는 쓰였다.
+    }
+}
+function writeState(path, state) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(state, null, 2), {
+        mode: STATE_FILE_MODE,
+    });
+    lockDown(path);
+}
+/**
+ * Phase 1 `bridge-state.json` → `accounts/default.json`. Never overwrites an
+ * existing account file. The legacy file is moved (not copied) so deleting
+ * `accounts/default.json` to force a re-pair cannot resurrect the old key.
+ */
+function migrateLegacyState(targetPath) {
+    const legacyPath = legacyBridgeStatePath();
+    if (existsSync(targetPath) || !existsSync(legacyPath))
+        return;
+    const legacy = readState(legacyPath);
+    if (!legacy)
+        return;
+    mkdirSync(dirname(targetPath), { recursive: true });
+    try {
+        renameSync(legacyPath, targetPath);
+        lockDown(targetPath);
+    }
+    catch {
+        // rename 이 막히면(권한·파일시스템) 내용 복사로 대체 — 원본은 남는다.
+        writeState(targetPath, legacy);
+    }
+}
+export function loadBridgeState(accountId) {
+    const path = bridgeStatePath(accountId);
+    if (accountId === DEFAULT_ACCOUNT_ID)
+        migrateLegacyState(path);
+    return readState(path);
+}
+export function saveBridgeState(accountId, state) {
+    writeState(bridgeStatePath(accountId), state);
+}