@useorgx/openclaw-plugin 0.4.8 → 0.7.0

package/dist/http/routes/agent-suite.d.ts

@@ -0,0 +1,38 @@
+import type { Router } from "../router.js";
+type JsonRecord = Record<string, unknown>;
+type ReadSkillPackStateFn = typeof import("../../skill-pack-state.js").readSkillPackState;
+type UpdateSkillPackPolicyFn = typeof import("../../skill-pack-state.js").updateSkillPackPolicy;
+type RollbackSkillPackPolicyFn = typeof import("../../skill-pack-state.js").rollbackSkillPackPolicy;
+type ComputeOrgxAgentSuitePlanFn = typeof import("../../agent-suite.js").computeOrgxAgentSuitePlan;
+type ApplyOrgxAgentSuitePlanFn = typeof import("../../agent-suite.js").applyOrgxAgentSuitePlan;
+type ClientRuntimeSettingsResponse = import("../../contracts/types.js").ClientRuntimeSettingsResponse;
+type ClientRuntimeSettingsUpdateRequest = import("../../contracts/types.js").ClientRuntimeSettingsUpdateRequest;
+type OrgxSkillPackOverrides = import("../../agent-suite.js").OrgxSkillPackOverrides;
+type RegisterAgentSuiteRoutesDeps<TReq, TRes> = {
+    pluginVersion: string | null | undefined;
+    telemetryDistinctId: string;
+    parseJsonRequest: (req: TReq) => Promise<JsonRecord>;
+    resolveSkillPackOverrides: (input: {
+        force?: boolean;
+    }) => Promise<OrgxSkillPackOverrides | null>;
+    readSkillPackState: ReadSkillPackStateFn;
+    computeOrgxAgentSuitePlan: ComputeOrgxAgentSuitePlanFn;
+    applyOrgxAgentSuitePlan: ApplyOrgxAgentSuitePlanFn;
+    generateAgentSuiteOperationId: () => string;
+    updateSkillPackPolicy: UpdateSkillPackPolicyFn;
+    rollbackSkillPackPolicy: RollbackSkillPackPolicyFn;
+    fetchAgentRuntimeSettings: (input?: {
+        workspaceId?: string | null;
+        projectId?: string | null;
+    }) => Promise<ClientRuntimeSettingsResponse>;
+    updateAgentRuntimeSettings: (payload: ClientRuntimeSettingsUpdateRequest) => Promise<ClientRuntimeSettingsResponse>;
+    posthogCapture: (input: {
+        event: string;
+        distinctId: string;
+        properties: Record<string, unknown>;
+    }) => Promise<unknown>;
+    sendJson: (res: TRes, status: number, payload: unknown) => void;
+    safeErrorMessage: (err: unknown) => string;
+};
+export declare function registerAgentSuiteRoutes<TReq, TRes>(router: Router<Record<string, never>, TReq, TRes>, deps: RegisterAgentSuiteRoutesDeps<TReq, TRes>): void;
+export {};

package/dist/http/routes/agent-suite.js

@@ -0,0 +1,397 @@
+function getPluginVersion(pluginVersion) {
+    const normalized = (pluginVersion ?? "").trim();
+    return normalized.length > 0 ? normalized : null;
+}
+function toRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function readBoolean(payload, ...keys) {
+    for (const key of keys) {
+        const value = payload[key];
+        if (typeof value === "boolean") {
+            return value;
+        }
+    }
+    return false;
+}
+function computeUpdateAvailable(state) {
+    return Boolean(state.remote?.checksum &&
+        state.pack?.checksum &&
+        state.remote.checksum !== state.pack.checksum);
+}
+function toOptionalString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function toOptionalUuid(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return UUID_RE.test(trimmed) ? trimmed : undefined;
+}
+function readOptionalBoolean(payload, ...keys) {
+    for (const key of keys) {
+        const value = payload[key];
+        if (typeof value === "boolean") {
+            return value;
+        }
+    }
+    return undefined;
+}
+function normalizeRuntimeSettingsPatch(payload) {
+    const runtime = toRecord(payload.runtime_settings ?? payload.runtimeSettings);
+    const patch = {};
+    const decisionV2Enabled = readOptionalBoolean(runtime, "decision_v2_enabled", "decisionV2Enabled");
+    if (typeof decisionV2Enabled === "boolean") {
+        patch.decision_v2_enabled = decisionV2Enabled;
+    }
+    const decisionDedupeEnabled = readOptionalBoolean(runtime, "decision_dedupe_enabled", "decisionDedupeEnabled");
+    if (typeof decisionDedupeEnabled === "boolean") {
+        patch.decision_dedupe_enabled = decisionDedupeEnabled;
+    }
+    const decisionEvidenceRequiredForBlocking = readOptionalBoolean(runtime, "decision_evidence_required_for_blocking", "decisionEvidenceRequiredForBlocking");
+    if (typeof decisionEvidenceRequiredForBlocking === "boolean") {
+        patch.decision_evidence_required_for_blocking =
+            decisionEvidenceRequiredForBlocking;
+    }
+    const decisionAutoResolveGuardedEnabled = readOptionalBoolean(runtime, "decision_auto_resolve_guarded_enabled", "decisionAutoResolveGuardedEnabled");
+    if (typeof decisionAutoResolveGuardedEnabled === "boolean") {
+        patch.decision_auto_resolve_guarded_enabled =
+            decisionAutoResolveGuardedEnabled;
+    }
+    const customRunInstructions = toOptionalString(runtime.custom_run_instructions ?? runtime.customRunInstructions);
+    if (typeof customRunInstructions === "string") {
+        patch.custom_run_instructions = customRunInstructions.slice(0, 4000);
+    }
+    return patch;
+}
+function buildRuntimeSettingsFallbackEnvelope(workspaceId) {
+    const normalizedWorkspaceId = typeof workspaceId === "string" && workspaceId.trim().length > 0
+        ? workspaceId.trim()
+        : null;
+    return {
+        ok: true,
+        workspace_id: normalizedWorkspaceId,
+        command_center_id: normalizedWorkspaceId,
+        project_id: normalizedWorkspaceId,
+        agents: [],
+    };
+}
+export function registerAgentSuiteRoutes(router, deps) {
+    async function renderStatus(res) {
+        try {
+            // Resolve skill pack overrides opportunistically; fallback to builtins.
+            let skillPack = null;
+            try {
+                skillPack = await deps.resolveSkillPackOverrides({});
+            }
+            catch {
+                // Ignore resolver errors and use local defaults.
+            }
+            const state = deps.readSkillPackState();
+            const plan = deps.computeOrgxAgentSuitePlan({
+                packVersion: deps.pluginVersion || "0.0.0",
+                skillPack,
+                skillPackRemote: state.remote,
+                skillPackPolicy: state.policy,
+                skillPackUpdateAvailable: computeUpdateAvailable(state),
+            });
+            deps.sendJson(res, 200, {
+                ok: true,
+                data: plan,
+            });
+        }
+        catch (err) {
+            deps.sendJson(res, 500, {
+                ok: false,
+                error: deps.safeErrorMessage(err),
+            });
+        }
+    }
+    router.add("GET", "agent-suite/status", async ({ res }) => renderStatus(res), "Agent suite installation status");
+    router.add("HEAD", "agent-suite/status", async ({ res }) => renderStatus(res), "Agent suite installation status (HEAD)");
+    router.add("GET", "agent-suite/runtime-settings", async ({ req, res }) => {
+        const requestUrl = new URL(String(req.url ?? "/"), "http://localhost");
+        const workspaceId = toOptionalUuid(requestUrl.searchParams.get("workspace_id") ??
+            requestUrl.searchParams.get("workspaceId") ??
+            requestUrl.searchParams.get("command_center_id") ??
+            requestUrl.searchParams.get("commandCenterId") ??
+            requestUrl.searchParams.get("project_id"));
+        try {
+            const response = await deps.fetchAgentRuntimeSettings({
+                workspaceId: workspaceId ?? null,
+            });
+            if (!response?.ok) {
+                deps.sendJson(res, 200, {
+                    ok: true,
+                    data: {
+                        ...buildRuntimeSettingsFallbackEnvelope(workspaceId ?? null),
+                        warning: response?.error ?? "Failed to load agent runtime settings",
+                    },
+                });
+                return;
+            }
+            deps.sendJson(res, 200, {
+                ok: true,
+                data: response,
+            });
+        }
+        catch (err) {
+            deps.sendJson(res, 200, {
+                ok: true,
+                data: {
+                    ...buildRuntimeSettingsFallbackEnvelope(workspaceId ?? null),
+                    warning: deps.safeErrorMessage(err),
+                },
+            });
+        }
+    }, "List agent runtime settings");
+    router.add("PATCH", "agent-suite/runtime-settings", async ({ req, res }) => {
+        try {
+            const payload = toRecord(await deps.parseJsonRequest(req));
+            const agentId = toOptionalString(payload.agent_id ?? payload.agentId)?.trim();
+            if (!agentId) {
+                deps.sendJson(res, 400, {
+                    ok: false,
+                    error: "agent_id is required",
+                });
+                return;
+            }
+            const runtimeSettingsPatch = normalizeRuntimeSettingsPatch(payload);
+            if (Object.keys(runtimeSettingsPatch).length === 0) {
+                deps.sendJson(res, 400, {
+                    ok: false,
+                    error: "runtime_settings must include at least one mutable field",
+                });
+                return;
+            }
+            const workspaceId = toOptionalUuid(payload.workspace_id ??
+                payload.workspaceId ??
+                payload.command_center_id ??
+                payload.commandCenterId ??
+                payload.project_id ??
+                payload.projectId);
+            const response = await deps.updateAgentRuntimeSettings({
+                agent_id: agentId,
+                ...(workspaceId
+                    ? {
+                        workspace_id: workspaceId,
+                        command_center_id: workspaceId,
+                    }
+                    : {}),
+                runtime_settings: runtimeSettingsPatch,
+            });
+            if (!response?.ok) {
+                deps.sendJson(res, 502, {
+                    ok: false,
+                    error: response?.error ?? "Failed to update agent runtime settings",
+                });
+                return;
+            }
+            deps.sendJson(res, 200, {
+                ok: true,
+                data: response,
+            });
+        }
+        catch (err) {
+            deps.sendJson(res, 500, {
+                ok: false,
+                error: deps.safeErrorMessage(err),
+            });
+        }
+    }, "Update agent runtime settings");
+    router.add("*", "agent-suite/runtime-settings", ({ res }) => {
+        deps.sendJson(res, 405, {
+            ok: false,
+            error: "Use GET/PATCH /orgx/api/agent-suite/runtime-settings",
+        });
+    }, "Reject unsupported methods for agent-suite/runtime-settings");
+    router.add("POST", "agent-suite/install", async ({ req, res }) => {
+        try {
+            const payload = toRecord(await deps.parseJsonRequest(req));
+            const dryRun = readBoolean(payload, "dryRun", "dry_run");
+            const forceSkillPack = readBoolean(payload, "forceSkillPack", "force_skill_pack");
+            const skillPack = await deps.resolveSkillPackOverrides({ force: forceSkillPack });
+            const state = deps.readSkillPackState();
+            const plan = deps.computeOrgxAgentSuitePlan({
+                packVersion: deps.pluginVersion || "0.0.0",
+                skillPack,
+                skillPackRemote: state.remote,
+                skillPackPolicy: state.policy,
+                skillPackUpdateAvailable: computeUpdateAvailable(state),
+            });
+            const result = deps.applyOrgxAgentSuitePlan({ plan, dryRun, skillPack });
+            const counts = {
+                create: 0,
+                update: 0,
+                noop: 0,
+                conflict: 0,
+            };
+            for (const entry of result.plan.workspaceFiles ?? []) {
+                if (entry.action in counts) {
+                    counts[entry.action] += 1;
+                }
+            }
+            void deps
+                .posthogCapture({
+                event: "openclaw_agent_suite_install",
+                distinctId: deps.telemetryDistinctId,
+                properties: {
+                    plugin_version: getPluginVersion(deps.pluginVersion),
+                    dry_run: Boolean(dryRun),
+                    applied: Boolean(result.applied),
+                    openclaw_config_updated: Boolean(result.plan.openclawConfigWouldUpdate),
+                    added_agents_count: result.plan.openclawConfigAddedAgents.length,
+                    files_create: counts.create,
+                    files_update: counts.update,
+                    files_noop: counts.noop,
+                    files_conflict: counts.conflict,
+                    skill_pack_source: result.plan.skillPack?.source ?? null,
+                    skill_pack_checksum: result.plan.skillPack?.checksum ?? null,
+                    skill_pack_version: result.plan.skillPack?.version ?? null,
+                },
+            })
+                .catch(() => {
+                // best effort
+            });
+            deps.sendJson(res, 200, {
+                ok: true,
+                operationId: deps.generateAgentSuiteOperationId(),
+                dryRun,
+                applied: result.applied,
+                data: result.plan,
+            });
+        }
+        catch (err) {
+            void deps
+                .posthogCapture({
+                event: "openclaw_agent_suite_install_failed",
+                distinctId: deps.telemetryDistinctId,
+                properties: {
+                    plugin_version: getPluginVersion(deps.pluginVersion),
+                    error: deps.safeErrorMessage(err),
+                },
+            })
+                .catch(() => {
+                // best effort
+            });
+            deps.sendJson(res, 500, {
+                ok: false,
+                error: deps.safeErrorMessage(err),
+            });
+        }
+    }, "Install managed OrgX agent suite");
+    router.add("*", "agent-suite/install", ({ res }) => {
+        deps.sendJson(res, 405, {
+            ok: false,
+            error: "Use POST /orgx/api/agent-suite/install",
+        });
+    }, "Reject unsupported methods for agent-suite/install");
+    router.add("GET", "skill-pack/policy", ({ res }) => {
+        const state = deps.readSkillPackState();
+        deps.sendJson(res, 200, {
+            ok: true,
+            data: {
+                policy: state.policy,
+                audit: state.audit,
+                pack: state.pack,
+                remote: state.remote,
+                updateAvailable: computeUpdateAvailable(state),
+                lastCheckedAt: state.lastCheckedAt,
+                lastError: state.lastError,
+            },
+        });
+    }, "Read skill-pack policy");
+    router.add("POST", "skill-pack/policy", async ({ req, res }) => {
+        try {
+            const payload = toRecord(await deps.parseJsonRequest(req));
+            const frozenRaw = payload.frozen;
+            const frozen = typeof frozenRaw === "boolean" ? frozenRaw : undefined;
+            const pinToCurrent = readBoolean(payload, "pinToCurrent", "pin_to_current");
+            const clearPin = readBoolean(payload, "clearPin", "clear_pin");
+            const changedByRaw = payload.changedBy ?? payload.changed_by;
+            const changedBy = typeof changedByRaw === "string" ? changedByRaw : undefined;
+            const reasonRaw = payload.reason;
+            const reason = typeof reasonRaw === "string" ? reasonRaw : undefined;
+            const actionRaw = payload.action;
+            const action = typeof actionRaw === "string" ? actionRaw.trim().toLowerCase() : "";
+            const rollbackToAuditIdRaw = payload.rollbackToAuditId ?? payload.rollback_to_audit_id;
+            const rollbackToAuditId = toOptionalString(rollbackToAuditIdRaw)?.trim() || undefined;
+            const pinnedChecksumRaw = payload.pinnedChecksum ?? payload.pinned_checksum;
+            const pinnedChecksum = typeof pinnedChecksumRaw === "string"
+                ? pinnedChecksumRaw
+                : pinnedChecksumRaw === null
+                    ? null
+                    : undefined;
+            const hasFrozen = typeof frozen === "boolean";
+            const hasPinnedChecksum = typeof pinnedChecksum === "string" || pinnedChecksum === null;
+            const hasPinToCurrent = pinToCurrent === true;
+            const hasClearPin = clearPin === true;
+            const isRollback = action === "rollback" || typeof rollbackToAuditId === "string";
+            if (action.length > 0 && action !== "rollback") {
+                throw new Error("action must be 'rollback' when provided.");
+            }
+            if (hasPinToCurrent && hasClearPin) {
+                throw new Error("pinToCurrent and clearPin cannot both be true.");
+            }
+            if (typeof pinnedChecksum === "string" && !pinnedChecksum.trim()) {
+                throw new Error("pinnedChecksum must be a non-empty string when provided.");
+            }
+            if (isRollback) {
+                if (hasFrozen || hasPinnedChecksum || hasPinToCurrent || hasClearPin) {
+                    throw new Error("Rollback requests cannot include update fields (frozen, pinnedChecksum, pinToCurrent, clearPin).");
+                }
+            }
+            else if (!hasFrozen && !hasPinnedChecksum && !hasPinToCurrent && !hasClearPin) {
+                throw new Error("Include at least one mutable field: frozen, pinnedChecksum, pinToCurrent, or clearPin.");
+            }
+            const state = isRollback
+                ? deps.rollbackSkillPackPolicy({
+                    auditId: rollbackToAuditId,
+                    changedBy,
+                    reason,
+                })
+                : deps.updateSkillPackPolicy({
+                    frozen,
+                    pinToCurrent,
+                    clearPin,
+                    pinnedChecksum: typeof pinnedChecksum === "string" ? pinnedChecksum.trim() : pinnedChecksum,
+                    changedBy,
+                    reason,
+                });
+            void deps
+                .posthogCapture({
+                event: "openclaw_skill_pack_policy_updated",
+                distinctId: deps.telemetryDistinctId,
+                properties: {
+                    plugin_version: getPluginVersion(deps.pluginVersion),
+                    frozen: state.policy.frozen,
+                    pinned_checksum_prefix: state.policy.pinnedChecksum
+                        ? state.policy.pinnedChecksum.slice(0, 12)
+                        : null,
+                },
+            })
+                .catch(() => {
+                // best effort
+            });
+            deps.sendJson(res, 200, {
+                ok: true,
+                data: {
+                    policy: state.policy,
+                    audit: state.audit,
+                },
+            });
+        }
+        catch (err) {
+            deps.sendJson(res, 400, { ok: false, error: deps.safeErrorMessage(err) });
+        }
+    }, "Update skill-pack policy");
+    router.add("*", "skill-pack/policy", ({ res }) => {
+        deps.sendJson(res, 405, {
+            ok: false,
+            error: "Use GET/POST /orgx/api/skill-pack/policy",
+        });
+    }, "Reject unsupported methods for skill-pack/policy");
+}

package/dist/http/routes/agents-catalog.d.ts

@@ -0,0 +1,40 @@
+import type { Router } from "../router.js";
+type OpenClawAgentEntry = {
+    id?: string;
+    name?: string;
+    workspace?: string;
+    model?: string;
+    isDefault?: boolean;
+};
+type LocalAgentSnapshot = {
+    id: string;
+    status: string;
+    currentTask: string | null;
+    runId: string | null;
+    startedAt: string | null;
+    blockers: string[];
+};
+type LocalSnapshot = {
+    agents: LocalAgentSnapshot[];
+};
+type AgentRun = {
+    agentId: string;
+    startedAt: string | null;
+    status: string;
+};
+type AgentRunStoreSnapshot = {
+    runs: Record<string, AgentRun & Record<string, unknown>>;
+};
+type AgentContextStoreSnapshot = {
+    agents: Record<string, unknown>;
+};
+type AgentsCatalogDeps<TRes> = {
+    listAgents: () => Promise<OpenClawAgentEntry[]>;
+    loadLocalSnapshot: () => Promise<LocalSnapshot | null>;
+    readAgentContexts: () => AgentContextStoreSnapshot;
+    readAgentRuns: () => AgentRunStoreSnapshot;
+    sendJson: (res: TRes, status: number, payload: unknown) => void;
+    safeErrorMessage: (err: unknown) => string;
+};
+export declare function registerAgentsCatalogRoutes<TReq, TRes>(router: Router<Record<string, never>, TReq, TRes>, deps: AgentsCatalogDeps<TRes>): void;
+export {};

package/dist/http/routes/agents-catalog.js

@@ -0,0 +1,128 @@
+export function registerAgentsCatalogRoutes(router, deps) {
+    async function handle(res) {
+        try {
+            let openclawAgents = [];
+            let openclawAgentsError = null;
+            try {
+                const fetched = await deps.listAgents();
+                openclawAgents = Array.isArray(fetched) ? fetched : [];
+            }
+            catch (err) {
+                openclawAgentsError = deps.safeErrorMessage(err);
+            }
+            const localSnapshot = await deps.loadLocalSnapshot().catch(() => null);
+            const localAgents = Array.isArray(localSnapshot?.agents)
+                ? localSnapshot.agents
+                : [];
+            const warnings = [];
+            if (openclawAgentsError) {
+                warnings.push(`openclaw agent discovery unavailable: ${openclawAgentsError}`);
+            }
+            const localById = new Map();
+            if (localAgents.length > 0) {
+                for (const agent of localAgents) {
+                    localById.set(agent.id, {
+                        status: agent.status,
+                        currentTask: agent.currentTask,
+                        runId: agent.runId,
+                        startedAt: agent.startedAt,
+                        blockers: agent.blockers,
+                    });
+                }
+            }
+            let contexts = {};
+            try {
+                contexts = deps.readAgentContexts().agents ?? {};
+            }
+            catch (err) {
+                warnings.push(`agent context snapshot unavailable: ${deps.safeErrorMessage(err)}`);
+            }
+            let runs = {};
+            try {
+                runs = deps.readAgentRuns().runs ?? {};
+            }
+            catch (err) {
+                warnings.push(`agent run snapshot unavailable: ${deps.safeErrorMessage(err)}`);
+            }
+            const latestRunByAgent = new Map();
+            const openclawById = new Map();
+            for (const run of Object.values(runs)) {
+                if (!run || typeof run !== "object")
+                    continue;
+                const agentId = typeof run.agentId === "string" ? run.agentId.trim() : "";
+                if (!agentId)
+                    continue;
+                const existing = latestRunByAgent.get(agentId);
+                const nextTs = Date.parse(run.startedAt ?? "");
+                const existingTs = existing ? Date.parse(existing.startedAt ?? "") : 0;
+                if (!existing) {
+                    latestRunByAgent.set(agentId, run);
+                    continue;
+                }
+                const existingRunning = existing.status === "running";
+                const nextRunning = run.status === "running";
+                if (nextRunning && !existingRunning) {
+                    latestRunByAgent.set(agentId, run);
+                    continue;
+                }
+                if (nextRunning === existingRunning && nextTs > existingTs) {
+                    latestRunByAgent.set(agentId, run);
+                }
+            }
+            for (const entry of openclawAgents) {
+                const id = typeof entry.id === "string" ? entry.id.trim() : "";
+                if (!id)
+                    continue;
+                openclawById.set(id, entry);
+            }
+            const candidateAgentIds = new Set();
+            for (const id of openclawById.keys())
+                candidateAgentIds.add(id);
+            for (const id of localById.keys())
+                candidateAgentIds.add(id);
+            for (const id of Object.keys(contexts ?? {})) {
+                const normalized = id.trim();
+                if (normalized)
+                    candidateAgentIds.add(normalized);
+            }
+            for (const id of latestRunByAgent.keys())
+                candidateAgentIds.add(id);
+            const agents = [...candidateAgentIds].sort((a, b) => a.localeCompare(b)).map((agentId) => {
+                const entry = openclawById.get(agentId) ?? null;
+                const name = typeof entry?.name === "string" && entry.name.trim().length > 0
+                    ? entry.name.trim()
+                    : agentId || "unknown";
+                const local = localById.get(agentId) ?? null;
+                const context = contexts[agentId] ?? null;
+                const runFromSession = local?.runId ? runs[local.runId] ?? null : null;
+                const run = runFromSession ?? (latestRunByAgent.get(agentId) ?? null);
+                return {
+                    id: agentId,
+                    name,
+                    workspace: typeof entry?.workspace === "string" ? entry.workspace : null,
+                    model: typeof entry?.model === "string" ? entry.model : null,
+                    isDefault: Boolean(entry?.isDefault),
+                    status: local?.status ?? null,
+                    currentTask: local?.currentTask ?? null,
+                    runId: local?.runId ?? null,
+                    startedAt: local?.startedAt ?? null,
+                    blockers: local?.blockers ?? [],
+                    context,
+                    run,
+                };
+            });
+            deps.sendJson(res, 200, {
+                generatedAt: new Date().toISOString(),
+                agents,
+                ...(warnings.length > 0 ? { warnings } : {}),
+            });
+        }
+        catch (err) {
+            deps.sendJson(res, 500, {
+                error: deps.safeErrorMessage(err),
+            });
+        }
+    }
+    router.add("GET", "agents/catalog", async ({ res }) => handle(res), "Agent catalog");
+    router.add("HEAD", "agents/catalog", async ({ res }) => handle(res), "Agent catalog (HEAD)");
+}

package/dist/http/routes/billing.d.ts

@@ -0,0 +1,23 @@
+import type { BillingCheckoutRequest } from "../../types.js";
+import type { Router } from "../router.js";
+type JsonRecord = Record<string, unknown>;
+type BillingClientLike = {
+    getBaseUrl: () => string;
+    getBillingStatus: () => Promise<unknown>;
+    createBillingCheckout: (input: BillingCheckoutRequest) => Promise<{
+        url?: string | null;
+        checkout_url?: string | null;
+    }>;
+    createBillingPortal: () => Promise<{
+        url?: string | null;
+    }>;
+};
+type RegisterBillingRoutesDeps<TReq, TRes> = {
+    client: BillingClientLike;
+    parseJsonRequest: (req: TReq) => Promise<JsonRecord>;
+    pickString: (input: JsonRecord, keys: string[]) => string | null;
+    sendJson: (res: TRes, status: number, payload: unknown) => void;
+    safeErrorMessage: (err: unknown) => string;
+};
+export declare function registerBillingRoutes<TReq, TRes>(router: Router<Record<string, never>, TReq, TRes>, deps: RegisterBillingRoutesDeps<TReq, TRes>): void;
+export {};

package/dist/http/routes/billing.js

@@ -0,0 +1,55 @@
+export function registerBillingRoutes(router, deps) {
+    router.add("GET", "billing/status", async ({ res }) => {
+        try {
+            const status = await deps.client.getBillingStatus();
+            deps.sendJson(res, 200, { ok: true, data: status });
+        }
+        catch (err) {
+            deps.sendJson(res, 200, { ok: false, error: deps.safeErrorMessage(err) });
+        }
+    }, "Get billing plan/status");
+    router.add("POST", "billing/checkout", async ({ req, res }) => {
+        const basePricingUrl = `${deps.client.getBaseUrl().replace(/\/+$/, "")}/pricing`;
+        try {
+            const payload = await deps.parseJsonRequest(req);
+            const planIdRaw = (deps.pickString(payload, ["planId", "plan_id", "plan"]) ?? "starter")
+                .trim()
+                .toLowerCase();
+            const billingCycleRaw = (deps.pickString(payload, ["billingCycle", "billing_cycle"]) ?? "monthly")
+                .trim()
+                .toLowerCase();
+            const planId = planIdRaw === "team" || planIdRaw === "enterprise" ? planIdRaw : "starter";
+            const billingCycle = billingCycleRaw === "annual" ? "annual" : "monthly";
+            const result = await deps.client.createBillingCheckout({
+                planId,
+                billingCycle,
+            });
+            const url = result?.url ?? result?.checkout_url ?? null;
+            deps.sendJson(res, 200, { ok: true, data: { url: url ?? basePricingUrl } });
+        }
+        catch {
+            // If remote billing endpoints are unavailable, degrade gracefully.
+            deps.sendJson(res, 200, { ok: true, data: { url: basePricingUrl } });
+        }
+    }, "Create billing checkout session");
+    router.add("POST", "billing/portal", async ({ res }) => {
+        const basePricingUrl = `${deps.client.getBaseUrl().replace(/\/+$/, "")}/pricing`;
+        try {
+            const result = await deps.client.createBillingPortal();
+            const url = result?.url ?? null;
+            deps.sendJson(res, 200, { ok: true, data: { url: url ?? basePricingUrl } });
+        }
+        catch {
+            deps.sendJson(res, 200, { ok: true, data: { url: basePricingUrl } });
+        }
+    }, "Create billing portal session");
+    router.add("*", "billing/status", ({ res }) => {
+        deps.sendJson(res, 405, { ok: false, error: "Method not allowed" });
+    }, "Reject unsupported methods for billing/status");
+    router.add("*", "billing/checkout", ({ res }) => {
+        deps.sendJson(res, 405, { ok: false, error: "Method not allowed" });
+    }, "Reject unsupported methods for billing/checkout");
+    router.add("*", "billing/portal", ({ res }) => {
+        deps.sendJson(res, 405, { ok: false, error: "Method not allowed" });
+    }, "Reject unsupported methods for billing/portal");
+}