forge-openclaw-plugin 0.2.3

package/README.md

@@ -0,0 +1,38 @@
+# Forge OpenClaw Plugin
+
+`forge-openclaw-plugin` is the publishable OpenClaw package for Forge.
+
+## Install
+
+Current OpenClaw builds should use package discovery:
+
+```bash
+openclaw plugins install forge-openclaw-plugin
+openclaw gateway restart
+```
+
+Older OpenClaw builds can keep using the repo/manual install path during the transition:
+
+```bash
+openclaw plugins install ./projects/forge
+openclaw gateway restart
+```
+
+That repo-local path is the fallback only. The published package stays on the SDK `definePluginEntry` entrypoint and does not rename the plugin, routes, tools, or config keys.
+
+## Recommended usage
+
+The public mental model is intentionally small:
+
+1. `forge_get_operator_overview`
+2. `forge_search_entities`
+3. `forge_create_entities` or `forge_update_entities`
+4. `forge_delete_entities` or `forge_restore_entities` when needed
+5. `forge_post_insight` for recommendations
+
+The skill is entity-format-driven. It teaches the agent how to:
+
+- keep the conversation natural
+- make only gentle end-of-message save suggestions
+- ask only for missing fields
+- capture goals, projects, tasks, values, patterns, behaviors, beliefs, and trigger reports

package/dist/openclaw/api-client.d.ts

@@ -0,0 +1,40 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export type ForgeHttpMethod = "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+export type ForgePluginConfig = {
+    baseUrl: string;
+    apiToken: string;
+    actorLabel: string;
+    timeoutMs: number;
+};
+export type CallForgeApiArgs = {
+    baseUrl: string;
+    apiToken?: string;
+    actorLabel?: string;
+    timeoutMs?: number;
+    method: ForgeHttpMethod;
+    path: string;
+    body?: unknown;
+    idempotencyKey?: string | null;
+    extraHeaders?: Record<string, string | null | undefined>;
+};
+export type ForgeProxyResponse = {
+    status: number;
+    body: unknown;
+};
+export declare class ForgePluginError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export declare function canBootstrapOperatorSession(baseUrl: string): boolean;
+export declare function callForgeApi(args: CallForgeApiArgs): Promise<ForgeProxyResponse>;
+export declare function readJsonRequestBody(request: IncomingMessage, options?: {
+    maxBytes?: number;
+    emptyObject?: boolean;
+}): Promise<unknown>;
+export declare function readSingleHeaderValue(headers: IncomingMessage["headers"], name: string): string | null;
+export declare function requireApiToken(config: ForgePluginConfig): void;
+export declare function writeJsonResponse(response: ServerResponse, status: number, body: unknown): void;
+export declare function writeForgeProxyResponse(response: ServerResponse, result: ForgeProxyResponse): void;
+export declare function writePluginError(response: ServerResponse, error: unknown): void;
+export declare function expectForgeSuccess(result: ForgeProxyResponse): unknown;

package/dist/openclaw/api-client.js

@@ -0,0 +1,273 @@
+import packageJson from "../../package.json" with { type: "json" };
+const DEFAULT_REQUEST_BODY_LIMIT = 256_000;
+const DEFAULT_RESPONSE_BODY_LIMIT = 2_000_000;
+const operatorSessionCookies = new Map();
+export class ForgePluginError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "ForgePluginError";
+    }
+}
+function normalizeBaseUrl(baseUrl) {
+    return baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+}
+function normalizeOrigin(baseUrl) {
+    return new URL(normalizeBaseUrl(baseUrl)).origin;
+}
+function isTailscaleIpv4(hostname) {
+    const match = hostname.match(/^(\d+)\.(\d+)\.(\d+)\.(\d+)$/);
+    if (!match) {
+        return false;
+    }
+    const [a, b] = match.slice(1).map((value) => Number(value));
+    return Number.isInteger(a) && Number.isInteger(b) && a === 100 && b >= 64 && b <= 127;
+}
+export function canBootstrapOperatorSession(baseUrl) {
+    const hostname = new URL(normalizeBaseUrl(baseUrl)).hostname.toLowerCase();
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname.endsWith(".ts.net") || isTailscaleIpv4(hostname);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function buildErrorBody(code, message) {
+    return {
+        ok: false,
+        error: {
+            code,
+            message
+        }
+    };
+}
+async function readReadableStreamBody(stream, maxBytes) {
+    const reader = stream.getReader();
+    const chunks = [];
+    let totalBytes = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            if (!value) {
+                continue;
+            }
+            totalBytes += value.byteLength;
+            if (totalBytes > maxBytes) {
+                throw new ForgePluginError(502, "forge_plugin_response_too_large", `Forge response exceeded ${maxBytes} bytes`);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const merged = new Uint8Array(totalBytes);
+    let offset = 0;
+    for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(merged);
+}
+async function readResponseBody(response, maxBytes = DEFAULT_RESPONSE_BODY_LIMIT) {
+    if (!response.body) {
+        return null;
+    }
+    const text = await readReadableStreamBody(response.body, maxBytes);
+    if (!text) {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return {
+            ok: false,
+            error: {
+                code: "forge_upstream_invalid_json",
+                message: text
+            }
+        };
+    }
+}
+function buildRequestHeaders(args) {
+    const headers = {
+        accept: "application/json",
+        "x-forge-source": "openclaw",
+        "x-forge-plugin-version": packageJson.version
+    };
+    if (args.actorLabel) {
+        headers["x-forge-actor"] = args.actorLabel;
+    }
+    if (args.apiToken) {
+        headers.authorization = `Bearer ${args.apiToken}`;
+    }
+    if (args.idempotencyKey) {
+        headers["idempotency-key"] = args.idempotencyKey;
+    }
+    if (args.body !== undefined) {
+        headers["content-type"] = "application/json";
+    }
+    for (const [name, value] of Object.entries(args.extraHeaders ?? {})) {
+        if (typeof value === "string" && value.trim().length > 0) {
+            headers[name] = value;
+        }
+    }
+    return headers;
+}
+async function ensureOperatorSessionCookie(baseUrl, timeoutMs) {
+    const origin = normalizeOrigin(baseUrl);
+    const cached = operatorSessionCookies.get(origin);
+    if (cached) {
+        return cached;
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(new URL("/api/v1/auth/operator-session", normalizeBaseUrl(baseUrl)), {
+            method: "GET",
+            headers: {
+                accept: "application/json",
+                "x-forge-source": "openclaw"
+            },
+            signal: controller.signal
+        });
+        const setCookie = response.headers.get("set-cookie");
+        if (!response.ok || !setCookie) {
+            throw new ForgePluginError(401, "forge_plugin_session_bootstrap_failed", "Forge did not issue an operator session. Add a token or use a trusted local/Tailscale Forge URL.");
+        }
+        const cookie = setCookie.split(";")[0]?.trim();
+        if (!cookie) {
+            throw new ForgePluginError(401, "forge_plugin_session_bootstrap_failed", "Forge issued an unusable operator session cookie.");
+        }
+        operatorSessionCookies.set(origin, cookie);
+        return cookie;
+    }
+    catch (error) {
+        if (error instanceof ForgePluginError) {
+            throw error;
+        }
+        const message = error instanceof Error && error.name === "AbortError"
+            ? `Forge operator-session bootstrap timed out after ${timeoutMs}ms`
+            : error instanceof Error
+                ? error.message
+                : String(error);
+        throw new ForgePluginError(502, "forge_plugin_session_bootstrap_failed", message);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export async function callForgeApi(args) {
+    return callForgeApiInternal(args, false);
+}
+async function callForgeApiInternal(args, retriedWithFreshSession) {
+    const controller = new AbortController();
+    const timeoutMs = Math.max(1000, args.timeoutMs ?? 15_000);
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    const sessionCookie = !args.apiToken && canBootstrapOperatorSession(args.baseUrl)
+        ? await ensureOperatorSessionCookie(args.baseUrl, timeoutMs)
+        : null;
+    try {
+        const response = await fetch(new URL(args.path, normalizeBaseUrl(args.baseUrl)), {
+            method: args.method,
+            headers: {
+                ...buildRequestHeaders(args),
+                ...(sessionCookie ? { cookie: sessionCookie } : {})
+            },
+            body: args.body === undefined ? undefined : JSON.stringify(args.body),
+            signal: controller.signal
+        });
+        if (!args.apiToken && sessionCookie && response.status === 401 && !retriedWithFreshSession) {
+            operatorSessionCookies.delete(normalizeOrigin(args.baseUrl));
+            return callForgeApiInternal(args, true);
+        }
+        const body = await readResponseBody(response);
+        return {
+            status: response.status,
+            body: body ?? (response.ok ? { ok: true } : buildErrorBody("forge_upstream_empty_response", `Forge API ${response.status} returned no body`))
+        };
+    }
+    catch (error) {
+        if (error instanceof ForgePluginError) {
+            throw error;
+        }
+        const message = error instanceof Error && error.name === "AbortError"
+            ? `Forge API request timed out after ${timeoutMs}ms`
+            : error instanceof Error
+                ? error.message
+                : String(error);
+        throw new ForgePluginError(502, "forge_plugin_upstream_unreachable", message);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export async function readJsonRequestBody(request, options = {}) {
+    const maxBytes = options.maxBytes ?? DEFAULT_REQUEST_BODY_LIMIT;
+    const chunks = [];
+    let totalBytes = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+        totalBytes += buffer.byteLength;
+        if (totalBytes > maxBytes) {
+            throw new ForgePluginError(413, "forge_plugin_body_too_large", `Request body exceeded ${maxBytes} bytes`);
+        }
+        chunks.push(buffer);
+    }
+    if (chunks.length === 0) {
+        return options.emptyObject ? {} : undefined;
+    }
+    const raw = Buffer.concat(chunks).toString("utf8").trim();
+    if (!raw) {
+        return options.emptyObject ? {} : undefined;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new ForgePluginError(400, "forge_plugin_invalid_json", error instanceof Error ? error.message : "Request body must be valid JSON");
+    }
+}
+export function readSingleHeaderValue(headers, name) {
+    const raw = headers[name.toLowerCase()];
+    if (Array.isArray(raw)) {
+        return raw[0] ?? null;
+    }
+    return typeof raw === "string" ? raw : null;
+}
+export function requireApiToken(config) {
+    if (config.apiToken.trim().length === 0 && !canBootstrapOperatorSession(config.baseUrl)) {
+        throw new ForgePluginError(401, "forge_plugin_token_required", "Forge apiToken is required for remote mutating plugin routes that cannot use local or Tailscale operator-session bootstrap");
+    }
+}
+export function writeJsonResponse(response, status, body) {
+    response.statusCode = status;
+    response.setHeader("content-type", "application/json; charset=utf-8");
+    response.end(JSON.stringify(body));
+}
+export function writeForgeProxyResponse(response, result) {
+    writeJsonResponse(response, result.status, result.body);
+}
+export function writePluginError(response, error) {
+    if (error instanceof ForgePluginError) {
+        writeJsonResponse(response, error.status, buildErrorBody(error.code, error.message));
+        return;
+    }
+    writeJsonResponse(response, 500, buildErrorBody("forge_plugin_internal_error", error instanceof Error ? error.message : String(error)));
+}
+export function expectForgeSuccess(result) {
+    if (result.status >= 400) {
+        const message = isRecord(result.body) &&
+            isRecord(result.body.error) &&
+            typeof result.body.error.message === "string"
+            ? result.body.error.message
+            : `Forge API returned ${result.status}`;
+        throw new ForgePluginError(result.status, "forge_plugin_upstream_error", message);
+    }
+    return result.body;
+}

package/dist/openclaw/index.d.ts

@@ -0,0 +1,10 @@
+import { forgePluginConfigSchema, registerForgePlugin, resolveForgePluginConfig } from "./plugin-entry-shared.js";
+declare const pluginEntry: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginConfigSchema;
+    register: NonNullable<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["register"]>;
+} & Pick<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition, "kind">;
+export default pluginEntry;
+export { forgePluginConfigSchema, registerForgePlugin, resolveForgePluginConfig };

package/dist/openclaw/index.js

@@ -0,0 +1,11 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { FORGE_PLUGIN_DESCRIPTION, FORGE_PLUGIN_ID, FORGE_PLUGIN_NAME, forgePluginConfigSchema, registerForgePlugin, resolveForgePluginConfig } from "./plugin-entry-shared.js";
+const pluginEntry = definePluginEntry({
+    id: FORGE_PLUGIN_ID,
+    name: FORGE_PLUGIN_NAME,
+    description: FORGE_PLUGIN_DESCRIPTION,
+    configSchema: forgePluginConfigSchema,
+    register: registerForgePlugin
+});
+export default pluginEntry;
+export { forgePluginConfigSchema, registerForgePlugin, resolveForgePluginConfig };

package/dist/openclaw/parity.d.ts

@@ -0,0 +1,9 @@
+export type ApiRouteKey = `${Uppercase<string>} ${string}`;
+export type ForgePluginRouteExclusion = {
+    method: Uppercase<string>;
+    path: string;
+    reason: "browser-session-telemetry" | "legacy-alias" | "operator-token-bootstrap" | "sse-forwarding";
+};
+export declare const FORGE_PLUGIN_ROUTE_EXCLUSIONS: ForgePluginRouteExclusion[];
+export declare function makeApiRouteKey(method: string, path: string): ApiRouteKey;
+export declare function collectExcludedApiRouteKeys(): Set<`${Uppercase<string>} ${string}`>;

package/dist/openclaw/parity.js

@@ -0,0 +1,39 @@
+export const FORGE_PLUGIN_ROUTE_EXCLUSIONS = [
+    {
+        method: "GET",
+        path: "/api/v1/campaigns",
+        reason: "legacy-alias"
+    },
+    {
+        method: "POST",
+        path: "/api/v1/settings/tokens",
+        reason: "operator-token-bootstrap"
+    },
+    {
+        method: "POST",
+        path: "/api/v1/settings/tokens/:id/rotate",
+        reason: "operator-token-bootstrap"
+    },
+    {
+        method: "POST",
+        path: "/api/v1/settings/tokens/:id/revoke",
+        reason: "operator-token-bootstrap"
+    },
+    {
+        method: "POST",
+        path: "/api/v1/session-events",
+        reason: "browser-session-telemetry"
+    },
+    {
+        method: "GET",
+        path: "/api/v1/events/stream",
+        reason: "sse-forwarding"
+    }
+];
+export function makeApiRouteKey(method, path) {
+    const normalizedPath = path.replaceAll(/\{([^}]+)\}/g, ":$1");
+    return `${method.toUpperCase()} ${normalizedPath}`;
+}
+export function collectExcludedApiRouteKeys() {
+    return new Set(FORGE_PLUGIN_ROUTE_EXCLUSIONS.map((route) => makeApiRouteKey(route.method, route.path)));
+}

package/dist/openclaw/plugin-entry-shared.d.ts

@@ -0,0 +1,8 @@
+import type { ForgePluginConfig } from "./api-client.js";
+import type { ForgePluginConfigSchema, ForgePluginRegistrationApi } from "./plugin-sdk-types.js";
+export declare const FORGE_PLUGIN_ID = "forge";
+export declare const FORGE_PLUGIN_NAME = "Forge";
+export declare const FORGE_PLUGIN_DESCRIPTION = "Thin OpenClaw adapter for the live Forge /api/v1 collaboration API.";
+export declare function resolveForgePluginConfig(pluginConfig: unknown): ForgePluginConfig;
+export declare const forgePluginConfigSchema: ForgePluginConfigSchema;
+export declare function registerForgePlugin(api: ForgePluginRegistrationApi): void;

package/dist/openclaw/plugin-entry-shared.js

@@ -0,0 +1,85 @@
+import { registerForgePluginCli, registerForgePluginRoutes } from "./routes.js";
+import { registerForgePluginTools } from "./tools.js";
+export const FORGE_PLUGIN_ID = "forge";
+export const FORGE_PLUGIN_NAME = "Forge";
+export const FORGE_PLUGIN_DESCRIPTION = "Thin OpenClaw adapter for the live Forge /api/v1 collaboration API.";
+function normalizeString(value, fallback) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : fallback;
+}
+function normalizeTimeout(value, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return fallback;
+    }
+    return Math.min(120_000, Math.max(1000, Math.round(value)));
+}
+export function resolveForgePluginConfig(pluginConfig) {
+    const raw = (pluginConfig ?? {});
+    return {
+        baseUrl: normalizeString(raw.baseUrl, "http://127.0.0.1:3017"),
+        apiToken: typeof raw.apiToken === "string" ? raw.apiToken.trim() : "",
+        actorLabel: normalizeString(raw.actorLabel, "aurel"),
+        timeoutMs: normalizeTimeout(raw.timeoutMs, 15_000)
+    };
+}
+export const forgePluginConfigSchema = {
+    parse(value) {
+        return resolveForgePluginConfig(value);
+    },
+    jsonSchema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+            baseUrl: {
+                type: "string",
+                default: "http://127.0.0.1:3017",
+                description: "Base URL of the live Forge API bridge."
+            },
+            apiToken: {
+                type: "string",
+                default: "",
+                description: "Optional bearer token for remote or explicit scoped access. Localhost and Tailscale Forge instances can bootstrap an operator session automatically."
+            },
+            actorLabel: {
+                type: "string",
+                default: "aurel",
+                description: "Actor label recorded in Forge provenance headers."
+            },
+            timeoutMs: {
+                type: "integer",
+                default: 15000,
+                minimum: 1000,
+                maximum: 120000,
+                description: "Timeout for proxy calls from the OpenClaw plugin to Forge."
+            }
+        }
+    },
+    uiHints: {
+        baseUrl: {
+            label: "Forge Base URL",
+            help: "Base URL of the live Forge API bridge.",
+            placeholder: "http://127.0.0.1:3017"
+        },
+        apiToken: {
+            label: "Forge API Token",
+            help: "Optional bearer token. Leave blank for one-step localhost or Tailscale operator-session bootstrap.",
+            sensitive: true,
+            placeholder: "fg_live_..."
+        },
+        actorLabel: {
+            label: "Actor Label",
+            help: "Recorded in Forge provenance headers for plugin-originated writes.",
+            placeholder: "aurel"
+        },
+        timeoutMs: {
+            label: "Request Timeout (ms)",
+            help: "Maximum time to wait before the plugin aborts an upstream Forge request.",
+            advanced: true
+        }
+    }
+};
+export function registerForgePlugin(api) {
+    const config = resolveForgePluginConfig(api.pluginConfig);
+    registerForgePluginRoutes(api, config);
+    registerForgePluginCli(api, config);
+    registerForgePluginTools(api, config);
+}

package/dist/openclaw/plugin-sdk-types.d.ts

@@ -0,0 +1,56 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { TSchema } from "@sinclair/typebox";
+import type { AgentToolResult } from "@mariozechner/pi-agent-core";
+export type ForgePluginConfigSchema = {
+    parse(value: unknown): unknown;
+    jsonSchema: Record<string, unknown>;
+    uiHints?: Record<string, ForgePluginConfigUiHint>;
+};
+export type ForgePluginConfigUiHint = {
+    label?: string;
+    help?: string;
+    placeholder?: string;
+    sensitive?: boolean;
+    advanced?: boolean;
+};
+export type ForgeRegisteredHttpRoute = {
+    path: string;
+    auth: "plugin" | "gateway";
+    match?: "exact" | "prefix";
+    handler: (request: IncomingMessage, response: ServerResponse) => Promise<boolean | void> | boolean | void;
+};
+export type ForgeRegisteredTool = {
+    name: string;
+    label: string;
+    description: string;
+    parameters: TSchema;
+    execute: (toolCallId: string, params: unknown) => Promise<AgentToolResult<unknown>>;
+};
+export type ForgeCliProgram = {
+    command(name: string): ForgeCliProgram;
+    description(text: string): ForgeCliProgram;
+    action(handler: () => Promise<void> | void): ForgeCliProgram;
+};
+export type ForgeCliRegistrarContext = {
+    program: ForgeCliProgram;
+    config: unknown;
+    logger: {
+        info?(message: string): void;
+        warn?(message: string): void;
+        error?(message: string): void;
+        debug?(message: string): void;
+    };
+};
+export type ForgePluginRegistrationApi = {
+    pluginConfig?: unknown;
+    registerHttpRoute(route: ForgeRegisteredHttpRoute): void;
+    registerTool(tool: ForgeRegisteredTool, options?: {
+        optional?: boolean;
+    }): void;
+    registerCli?(registrar: (context: ForgeCliRegistrarContext) => void, options?: {
+        commands?: string[];
+    }): void;
+};
+export type ForgePluginRouteApi = Pick<ForgePluginRegistrationApi, "registerHttpRoute">;
+export type ForgePluginToolApi = Pick<ForgePluginRegistrationApi, "registerTool">;
+export type ForgePluginCliApi = Pick<ForgePluginRegistrationApi, "registerCli">;

package/dist/openclaw/plugin-sdk-types.js

@@ -0,0 +1 @@
+export {};

package/dist/openclaw/routes.d.ts

@@ -0,0 +1,27 @@
+import { type ForgeHttpMethod, type ForgePluginConfig } from "./api-client.js";
+import { type ApiRouteKey } from "./parity.js";
+import type { ForgePluginCliApi, ForgePluginRouteApi, ForgeRegisteredHttpRoute } from "./plugin-sdk-types.js";
+type PluginRouteMatch = NonNullable<ForgeRegisteredHttpRoute["match"]>;
+type RouteOperation = {
+    method: ForgeHttpMethod;
+    pattern: RegExp;
+    upstreamPath: string;
+    target: (match: RegExpMatchArray, url: URL) => string;
+    requiresToken?: boolean;
+    requestBody?: "json";
+};
+type RouteGroup = {
+    path: string;
+    match: PluginRouteMatch;
+    operations: RouteOperation[];
+};
+export declare const FORGE_PLUGIN_ROUTE_GROUPS: RouteGroup[];
+export declare function collectMirroredApiRouteKeys(): Set<ApiRouteKey>;
+export declare function buildRouteParityReport(pathMap: Record<string, Record<string, unknown>>): {
+    mirrored: `${Uppercase<string>} ${string}`[];
+    excluded: `${Uppercase<string>} ${string}`[];
+    uncovered: `${Uppercase<string>} ${string}`[];
+};
+export declare function registerForgePluginRoutes(api: ForgePluginRouteApi, config: ForgePluginConfig): void;
+export declare function registerForgePluginCli(api: ForgePluginCliApi, config: ForgePluginConfig): void;
+export {};