@mininglamp-oss/octo-runtime 0.0.0-stage → 1.0.0

package/node_modules/@mininglamp-oss/octo-runtime-extra-channel-gateway/dist/transport/api/cards.js

@@ -0,0 +1,225 @@
+import { MessageType } from "./types.js";
+import { postJson, generateClientMsgNo, DEFAULT_TIMEOUT_MS } from "./client.js";
+import { OctoApiError } from "./errors.js";
+function validateTemplateFrame(params) {
+    const templateRef = params.templateRef;
+    if (templateRef === null || typeof templateRef !== "object" || Array.isArray(templateRef)) {
+        throw new Error("octo: templateRef must contain exactly id and version");
+    }
+    const templateRefKeys = Object.keys(templateRef);
+    if (templateRefKeys.length !== 2 ||
+        !templateRefKeys.includes("id") ||
+        !templateRefKeys.includes("version")) {
+        throw new Error("octo: templateRef must contain exactly id and version");
+    }
+    const { id, version } = templateRef;
+    if (typeof id !== "string" || typeof version !== "string" || !id.trim() || !version.trim()) {
+        throw new Error("octo: templateRef id/version are required");
+    }
+    if (typeof params.state !== "string" || !params.state.trim()) {
+        throw new Error("octo: template state is required");
+    }
+    const data = params.data;
+    if (data === null ||
+        typeof data !== "object" ||
+        Array.isArray(data) ||
+        (Object.getPrototypeOf(data) !== Object.prototype && Object.getPrototypeOf(data) !== null) ||
+        !Object.hasOwn(data, "state")) {
+        throw new Error("octo: data must be a plain object with own state");
+    }
+    if (data.state !== params.state) {
+        throw new Error("octo: data.state must match state");
+    }
+}
+/**
+ * Send one Registry-authored type-17 card without any Model B render-owned fields.
+ *
+ * `onBehalfOf` is intentionally absent (unlike {@link sendCardMessage}): Registry template cards
+ * are bot-authored by design, and OBO + type-17 is rejected by P1 Decision 2b — persona-clone
+ * turns skip progress cards entirely in `card-progress.ts`.
+ */
+export async function sendTemplateCardMessage(params) {
+    if (!params.channelId.trim()) {
+        throw new Error("octo: channelId is required to send a message");
+    }
+    validateTemplateFrame(params);
+    return await postJson(params.apiUrl, params.botToken, "/v1/bot/sendMessage", {
+        channel_id: params.channelId,
+        channel_type: params.channelType,
+        payload: {
+            type: MessageType.InteractiveCard,
+            template_ref: params.templateRef,
+            state: params.state,
+            data: params.data
+        },
+        client_msg_no: params.clientMsgNo ?? generateClientMsgNo()
+    }, params.signal, { retryOn429: params.retryOn429 ?? true });
+}
+/** Replace one Registry-authored card frame; raw content_edit is intentionally unavailable. */
+export async function editTemplateCardMessage(params) {
+    if (!params.messageId)
+        throw new Error("octo: messageId is required to edit a card");
+    if (!params.channelId.trim())
+        throw new Error("octo: channelId is required to edit a card");
+    if (!Number.isSafeInteger(params.cardSeq) || params.cardSeq <= 0) {
+        throw new Error("octo: cardSeq must be a positive safe integer");
+    }
+    validateTemplateFrame(params);
+    await postJson(params.apiUrl, params.botToken, "/v1/bot/message/edit", {
+        message_id: params.messageId,
+        channel_id: params.channelId,
+        channel_type: params.channelType,
+        template_ref: params.templateRef,
+        state: params.state,
+        data: params.data,
+        card_seq: params.cardSeq,
+        ...(params.transient ? { transient: true } : {})
+    }, params.signal, { retryOn429: params.retryOn429 ?? true });
+}
+function stringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : [];
+}
+function parseTemplatingCapability(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const root = value;
+    const templates = [];
+    for (const candidate of Array.isArray(root.templates) ? root.templates : []) {
+        if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+            continue;
+        const template = candidate;
+        if (typeof template.id !== "string" || typeof template.version !== "string")
+            continue;
+        const views = [];
+        for (const candidateView of Array.isArray(template.views) ? template.views : []) {
+            if (!candidateView || typeof candidateView !== "object" || Array.isArray(candidateView))
+                continue;
+            const view = candidateView;
+            if (typeof view.name !== "string" || typeof view.wire_profile !== "string")
+                continue;
+            views.push({
+                name: view.name,
+                wire_profile: view.wire_profile,
+                states: stringArray(view.states),
+                submit_actions: stringArray(view.submit_actions)
+            });
+        }
+        templates.push({
+            id: template.id,
+            version: template.version,
+            views,
+            ...(typeof template.available === "boolean" ? { available: template.available } : {})
+        });
+    }
+    return {
+        supported: root.supported === true,
+        wire: typeof root.wire === "string" ? root.wire : "",
+        templates
+    };
+}
+function parseCardTemplateRef(value) {
+    if (value === null)
+        return null;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const ref = value;
+    if (Object.keys(ref).length !== 2 ||
+        typeof ref.id !== "string" ||
+        !ref.id ||
+        ref.id.trim() !== ref.id ||
+        typeof ref.version !== "string" ||
+        !ref.version ||
+        ref.version.trim() !== ref.version) {
+        return undefined;
+    }
+    return { id: ref.id, version: ref.version };
+}
+function parseBotCardConfig(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const config = value;
+    if (typeof config.card_enabled !== "boolean" ||
+        typeof config.display_enabled !== "boolean" ||
+        typeof config.interaction_enabled !== "boolean" ||
+        typeof config.reasoning_enabled !== "boolean") {
+        return undefined;
+    }
+    if (!config.card_enabled &&
+        (config.display_enabled || config.interaction_enabled || config.reasoning_enabled)) {
+        return undefined;
+    }
+    const reasoningRef = parseCardTemplateRef(config.reasoning_template_ref);
+    // The server guarantees this invariant. Reject a malformed response rather than guessing a
+    // policy locally: a permissive normalization could re-enable a card the Bot owner disabled.
+    if (reasoningRef === undefined ||
+        (config.reasoning_enabled && reasoningRef === null) ||
+        (!config.reasoning_enabled && reasoningRef !== null)) {
+        return undefined;
+    }
+    return {
+        card_enabled: config.card_enabled,
+        display_enabled: config.display_enabled,
+        interaction_enabled: config.interaction_enabled,
+        reasoning_enabled: config.reasoning_enabled,
+        reasoning_template_ref: reasoningRef
+    };
+}
+/**
+ * GET /v1/bot/card/profile — D12 能力发现。发卡前 feature-detect，避免用发送试探
+ * （一个 400 无法区分「disabled」与「invalid」）。
+ *
+ * 返回 `available` 区分端点未部署与已部署；两者都由调用方 fail closed：
+ *   - 端点未部署（404）→ `{ available:false }`。
+ *   - 端点已部署但缺失/非法 `config` → `{ available:true }` 且无 `config`。
+ * 传输 / 5xx 抛错，交由调用方重试节奏处理。
+ */
+export async function getCardProfile(params) {
+    const url = `${params.apiUrl.replace(/\/+$/, "")}/v1/bot/card/profile`;
+    const resp = await fetch(url, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${params.botToken}` },
+        signal: params.signal ?? AbortSignal.timeout(DEFAULT_TIMEOUT_MS)
+    });
+    // 端点尚未部署时 fail closed；不使用本地开关猜测服务端 Bot 策略。
+    if (resp.status === 404)
+        return { available: false, enabled: false };
+    if (!resp.ok) {
+        const text = await resp.text().catch(() => "");
+        // Structured, so a caller can tell a rate limit from any other failure and honour the
+        // wait the server asked for. This is the one hot path that does not go through postJson,
+        // and flattening a 429 into a generic Error here threw away the Retry-After that the
+        // progress-card cooldown needs.
+        throw OctoApiError.from(resp, "GET /v1/bot/card/profile", text);
+    }
+    // 端点已部署（available:true）；manifest 内容异常时保守视作 enabled:false。
+    const raw = (await resp.json().catch(() => null));
+    if (!raw || typeof raw !== "object")
+        return { available: true, enabled: false };
+    const templating = parseTemplatingCapability(raw.templating);
+    const config = parseBotCardConfig(raw.config);
+    return {
+        available: raw.available !== false,
+        // 兼容布尔与 1/0 序列化(与本仓 GroupMember.robot / getMentionPref 的 flag 惯例一致)。
+        enabled: raw.enabled === true || raw.enabled === 1,
+        ...(Array.isArray(raw.profiles)
+            ? { profiles: raw.profiles.filter((e) => typeof e === "string") }
+            : {}),
+        ...(typeof raw.card_version === "string" ? { card_version: raw.card_version } : {}),
+        ...(Array.isArray(raw.elements)
+            ? { elements: raw.elements.filter((e) => typeof e === "string") }
+            : {}),
+        ...(Array.isArray(raw.inputs)
+            ? { inputs: raw.inputs.filter((e) => typeof e === "string") }
+            : {}),
+        ...(Array.isArray(raw.actions)
+            ? { actions: raw.actions.filter((e) => typeof e === "string") }
+            : {}),
+        ...(raw.limits && typeof raw.limits === "object"
+            ? { limits: raw.limits }
+            : {}),
+        ...(templating ? { templating } : {}),
+        ...(config ? { config } : {})
+    };
+}

package/node_modules/@mininglamp-oss/octo-runtime-extra-channel-gateway/dist/transport/api/client.d.ts

@@ -0,0 +1,57 @@
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * 生成出站消息的客户端幂等编号 client_msg_no（UUID）。
+ *
+ * WuKongIM 以 client_msg_no 做服务端去重（见 pkg/wkdb/message.go：相同
+ * client_msg_no 只落库一条）。图文混排 payload 体积大、链路长、更易触发重试，
+ * 故出站统一附带 client_msg_no，保证重试不会产生重复消息。
+ */
+export declare function generateClientMsgNo(): string;
+/**
+ * Parse JSON with int64 message_id protection.
+ * Converts 16+ digit numeric message_id values to strings before JSON.parse
+ * to prevent JavaScript precision loss for IDs exceeding Number.MAX_SAFE_INTEGER.
+ */
+export declare function parseOctoJson<T>(text: string): T;
+/** At most three attempts per call: the original plus two retries. */
+export declare const MAX_429_RETRIES = 2;
+/**
+ * A wait longer than this is not worth holding the call for. Used only to decide whether
+ * to retry — never to shorten the server's requested wait, because a shortened wait means
+ * going back before the server said we could.
+ */
+export declare const MAX_RETRY_AFTER_MS = 10000;
+/** Cumulative backoff sleep budget for one call. Not an end-to-end deadline. */
+export declare const MAX_429_BACKOFF_WAIT_MS = 15000;
+/**
+ * Deadline applied to a POST when the caller expresses none of its own.
+ *
+ * `fetch` has no default timeout, so without this a hung connection blocks its caller
+ * indefinitely. Callers that pass a signal keep full control: the events long poll asks
+ * for far more than this on purpose, and intersecting the two would abort a legitimate
+ * hold and discard the batch the server was about to return.
+ */
+export declare const DEFAULT_POST_TIMEOUT_MS = 30000;
+/**
+ * Absolute ceiling on one POST attempt, applied even when the caller supplied its own signal.
+ *
+ * The caller's signal is honoured as-is for anything under this, because it knows what this
+ * particular request needs — the events long poll deliberately asks for up to 40s and cutting
+ * it short would abort a legitimate hold. But a signal that carries no deadline at all would
+ * otherwise make the request unbounded, which is the class of hang this module is trying to
+ * remove; nothing here has any business running for a full minute.
+ */
+export declare const POST_HARD_CEILING_MS = 60000;
+interface JsonRequestOptions {
+    retryOn429?: boolean;
+    /** Receipt uploads use the caller's throttled diagnostic instead. */
+    logRateLimit?: boolean;
+    idempotencyKey?: string;
+    expectedStatus?: number;
+    redirect?: "error" | "follow" | "manual";
+    /** Optional decoded response cap for callers that fetch large documents. */
+    maxResponseBytes?: number;
+}
+export declare function postJson<T>(apiUrl: string, botToken: string, path: string, payload: Record<string, unknown>, signal?: AbortSignal, opts?: JsonRequestOptions): Promise<T | undefined>;
+export declare function getJson<T>(apiUrl: string, botToken: string, path: string, signal?: AbortSignal, opts?: JsonRequestOptions): Promise<T | undefined>;
+export {};

package/node_modules/@mininglamp-oss/octo-runtime-extra-channel-gateway/dist/transport/api/client.js

@@ -0,0 +1,184 @@
+/**
+ * HTTP 基础设施：统一鉴权请求、超时、限流重试和 64 位消息 ID 解析。
+ * 防止 ID 精度丢失与无限等待；不读取 CLI 配置，也不记录 token。
+ */
+// Adapted from Mininglamp-OSS/openclaw-channel-octo/src/api-fetch.ts.
+import { randomUUID } from "node:crypto";
+import { OctoApiError, OctoApiStatusMismatchError, OctoApiProtocolError } from "./errors.js";
+export const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * 生成出站消息的客户端幂等编号 client_msg_no（UUID）。
+ *
+ * WuKongIM 以 client_msg_no 做服务端去重（见 pkg/wkdb/message.go：相同
+ * client_msg_no 只落库一条）。图文混排 payload 体积大、链路长、更易触发重试，
+ * 故出站统一附带 client_msg_no，保证重试不会产生重复消息。
+ */
+export function generateClientMsgNo() {
+    return randomUUID();
+}
+const DEFAULT_HEADERS = {
+    "Content-Type": "application/json"
+};
+/**
+ * Parse JSON with int64 message_id protection.
+ * Converts 16+ digit numeric message_id values to strings before JSON.parse
+ * to prevent JavaScript precision loss for IDs exceeding Number.MAX_SAFE_INTEGER.
+ */
+export function parseOctoJson(text) {
+    const safeText = text.replace(/"message_id"\s*:\s*(\d{16,})/g, '"message_id":"$1"');
+    return JSON.parse(safeText);
+}
+/** At most three attempts per call: the original plus two retries. */
+export const MAX_429_RETRIES = 2;
+/**
+ * A wait longer than this is not worth holding the call for. Used only to decide whether
+ * to retry — never to shorten the server's requested wait, because a shortened wait means
+ * going back before the server said we could.
+ */
+export const MAX_RETRY_AFTER_MS = 10_000;
+/** Cumulative backoff sleep budget for one call. Not an end-to-end deadline. */
+export const MAX_429_BACKOFF_WAIT_MS = 15_000;
+/**
+ * Deadline applied to a POST when the caller expresses none of its own.
+ *
+ * `fetch` has no default timeout, so without this a hung connection blocks its caller
+ * indefinitely. Callers that pass a signal keep full control: the events long poll asks
+ * for far more than this on purpose, and intersecting the two would abort a legitimate
+ * hold and discard the batch the server was about to return.
+ */
+export const DEFAULT_POST_TIMEOUT_MS = DEFAULT_TIMEOUT_MS;
+/**
+ * Absolute ceiling on one POST attempt, applied even when the caller supplied its own signal.
+ *
+ * The caller's signal is honoured as-is for anything under this, because it knows what this
+ * particular request needs — the events long poll deliberately asks for up to 40s and cutting
+ * it short would abort a legitimate hold. But a signal that carries no deadline at all would
+ * otherwise make the request unbounded, which is the class of hang this module is trying to
+ * remove; nothing here has any business running for a full minute.
+ */
+export const POST_HARD_CEILING_MS = 60_000;
+/** Sleep that rejects as soon as the caller's signal aborts, preserving `cause`. */
+function backoffSleep(ms, signal, cause) {
+    const aborted = () => new Error("aborted while backing off from a rate limit", { cause });
+    // Checked before arming anything: an abort that landed between the response returning
+    // and this call would otherwise be missed entirely and we would serve the full wait.
+    if (signal?.aborted)
+        return Promise.reject(aborted());
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            // Surface the rate limiting as the cause; without it the failure site shows only a
+            // generic abort and the 429 diagnosis is lost.
+            reject(aborted());
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+async function readResponseText(response, maxBytes) {
+    if (maxBytes === undefined)
+        return response.text();
+    const reader = response.body?.getReader();
+    if (!reader)
+        return "";
+    let bytes = 0;
+    const chunks = [];
+    try {
+        // Content-Length can understate a compressed or chunked response, so the
+        // decoded stream remains authoritative even after this early rejection.
+        if (Number(response.headers.get("content-length")) > maxBytes) {
+            throw new Error("Octo API response exceeds byte limit");
+        }
+        for (;;) {
+            const { done, value } = (await reader.read());
+            if (done)
+                break;
+            if (!(value instanceof Uint8Array))
+                throw new Error("Octo API response stream is invalid");
+            bytes += value.byteLength;
+            if (bytes > maxBytes)
+                throw new Error("Octo API response exceeds byte limit");
+            chunks.push(Buffer.from(value));
+        }
+        return Buffer.concat(chunks, bytes).toString("utf8");
+    }
+    catch (error) {
+        await reader.cancel().catch(() => { });
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+async function requestJson(apiUrl, botToken, path, method, payload, signal, opts = {}) {
+    const url = `${apiUrl.replace(/\/+$/, "")}${path}`;
+    const retryOn429 = opts.retryOn429 ?? true;
+    let waited = 0;
+    for (let attempt = 0;; attempt++) {
+        if (signal?.aborted)
+            throw signal.reason;
+        // Rebuilt per attempt: a deadline created once outside the loop is shared across
+        // attempts, so a retry could start on a budget the first attempt already spent.
+        const fetchSignal = signal
+            ? AbortSignal.any([signal, AbortSignal.timeout(POST_HARD_CEILING_MS)])
+            : AbortSignal.timeout(DEFAULT_POST_TIMEOUT_MS);
+        const response = await fetch(url, {
+            method,
+            headers: {
+                ...(payload ? DEFAULT_HEADERS : {}),
+                Authorization: `Bearer ${botToken}`,
+                ...(opts.idempotencyKey ? { "Idempotency-Key": opts.idempotencyKey } : {})
+            },
+            ...(payload ? { body: JSON.stringify(payload) } : {}),
+            signal: fetchSignal,
+            ...(opts.redirect ? { redirect: opts.redirect } : {})
+        });
+        if (response.ok) {
+            if (opts.expectedStatus !== undefined && response.status !== opts.expectedStatus) {
+                throw new OctoApiStatusMismatchError(path, response.status, opts.expectedStatus);
+            }
+            const text = await readResponseText(response, opts.maxResponseBytes);
+            if (!text)
+                return undefined;
+            try {
+                return parseOctoJson(text);
+            }
+            catch {
+                throw new OctoApiProtocolError(`Octo API ${path} returned invalid JSON: ${text.slice(0, 200)}`);
+            }
+        }
+        const body = await readResponseText(response, opts.maxResponseBytes).catch(() => "");
+        const err = OctoApiError.from(response, path, body);
+        if (!err.isRateLimited)
+            throw err;
+        // Logged on every rate limit, including the one we give up on: the scope and the
+        // remaining count are the only way to tell which bucket ran dry and whose traffic
+        // filled it, and they are discarded once this error leaves here.
+        if (opts.logRateLimit !== false)
+            console.warn(`octo: rate limited on ${path} (scope=${err.rateLimitScope ?? "?"} ` +
+                `remaining=${err.rateLimitRemaining ?? "?"} retry_after=${err.retryAfterMs}ms) ` +
+                `attempt=${attempt + 1}/${retryOn429 ? MAX_429_RETRIES + 1 : 1}`);
+        if (!retryOn429 || attempt >= MAX_429_RETRIES)
+            throw err;
+        // A wait this long is the server telling us to go away, not to try again shortly.
+        // Clamping it down instead would just return before it was ready for us.
+        if (err.retryAfterMs > MAX_RETRY_AFTER_MS)
+            throw err;
+        // Jitter only ever adds. Retry-After is the earliest acceptable retry time, so a
+        // downward jitter would put us back on the server before it allowed it.
+        const delay = Math.round(err.retryAfterMs * (1 + Math.random() * 0.25));
+        if (waited + delay > MAX_429_BACKOFF_WAIT_MS)
+            throw err;
+        await backoffSleep(delay, signal, err);
+        waited += delay;
+    }
+}
+export async function postJson(apiUrl, botToken, path, payload, signal, opts) {
+    return requestJson(apiUrl, botToken, path, "POST", payload, signal, opts);
+}
+export async function getJson(apiUrl, botToken, path, signal, opts) {
+    return requestJson(apiUrl, botToken, path, "GET", undefined, signal, opts);
+}

package/node_modules/@mininglamp-oss/octo-runtime-extra-channel-gateway/dist/transport/api/conversations.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 会话读取 API：获取群、成员、用户与消息历史，保留平台身份和消息顺序信息。
+ * 读取权限由 IM Server 决定，调用方负责选择本轮材料，接口层不组装 prompt。
+ */
+import type { ChannelType } from "./types.js";
+export declare function fetchBotGroups(params: {
+    apiUrl: string;
+    botToken: string;
+    log?: {
+        info?: (msg: string) => void;
+        error?: (msg: string) => void;
+    };
+}): Promise<Array<{
+    group_no: string;
+    name: string;
+}>>;
+/**
+ * 获取群成员列表
+ */
+export interface GroupMember {
+    uid: string;
+    name: string;
+    role?: string;
+    robot?: boolean | number;
+}
+export declare function getGroupMembers(params: {
+    apiUrl: string;
+    botToken: string;
+    groupNo: string;
+    signal?: AbortSignal;
+    log?: {
+        info?: (msg: string) => void;
+        error?: (msg: string) => void;
+    };
+}): Promise<GroupMember[]>;
+/** Decoded payload from base64 message content */
+interface SyncMessagePayload {
+    type?: number;
+    content?: string;
+    url?: string;
+    name?: string;
+    mention?: {
+        all?: boolean;
+        uids?: string[];
+    };
+}
+/**
+ * 获取频道历史消息（用于注入上下文）
+ * @param params.log - Optional logger for consistent logging with OpenClaw log system
+ */
+export declare function getChannelMessages(params: {
+    apiUrl: string;
+    botToken: string;
+    channelId: string;
+    channelType: ChannelType;
+    limit?: number;
+    startMessageSeq?: number;
+    endMessageSeq?: number;
+    pullMode?: 0 | 1;
+    signal?: AbortSignal;
+    log?: {
+        info?: (msg: string) => void;
+        error?: (msg: string) => void;
+    };
+}): Promise<Array<{
+    from_uid: string;
+    content: string;
+    timestamp: number;
+    message_id?: string;
+    message_seq?: number;
+    type?: number;
+    url?: string;
+    name?: string;
+    payload?: SyncMessagePayload;
+}>>;
+/**
+ * Fetch user info by UID. Requires backend `/v1/bot/user/info` endpoint.
+ * Returns null if the endpoint is unavailable (404) or returns an error,
+ * so callers can gracefully degrade.
+ */
+export declare function fetchUserInfo(params: {
+    apiUrl: string;
+    botToken: string;
+    uid: string;
+    log?: {
+        info?: (msg: string) => void;
+        error?: (msg: string) => void;
+    };
+}): Promise<{
+    uid: string;
+    name: string;
+    avatar?: string;
+} | null>;
+export declare function searchSpaceMembers(params: {
+    apiUrl: string;
+    botToken: string;
+    keyword?: string;
+    spaceId?: string;
+    limit?: number;
+}): Promise<Array<{
+    uid: string;
+    name: string;
+    robot: number;
+}>>;
+export {};