@supen-ai/cli 0.1.6

package/daemon/dist/channels/http-routes.js

@@ -0,0 +1,688 @@
+/**
+ * Supen Daemon — declarative route registry.
+ *
+ * This is the single source of truth for all HTTP routes. Both:
+ *   1. The OpenAPI spec is generated from here and advertises canonical
+ *      /api/computers/{computer_id} routes for computer-scoped APIs.
+ *   2. Route matching in http.ts can reference ROUTES for consistency.
+ *
+ * Adding a new endpoint? Add an entry here. The spec updates automatically.
+ */
+// Common reusable params
+const agentId = {
+    name: "agent_id",
+    in: "path",
+    required: true,
+    type: "string",
+};
+const sessionId = {
+    name: "session_id",
+    in: "path",
+    required: true,
+    type: "string",
+};
+const threadId = {
+    name: "thread_id",
+    in: "path",
+    required: true,
+    type: "string",
+};
+const automationId = {
+    name: "id",
+    in: "path",
+    required: true,
+    type: "string",
+};
+const computerId = {
+    name: "computer_id",
+    in: "path",
+    required: true,
+    type: "string",
+    description: "Computer identifier used by canonical computer-scoped routes.",
+};
+const skillName = {
+    name: "name",
+    in: "path",
+    required: true,
+    type: "string",
+};
+export const ROUTES = [
+    // ── Computer ──────────────────────────────────────────────────────────────
+    { method: "GET", path: "/health", tag: "Computer", summary: "Health check" },
+    {
+        method: "GET",
+        path: "/api/computer/openapi.json",
+        tag: "Computer",
+        summary: "OpenAPI document for computer routes",
+    },
+    {
+        method: "POST",
+        path: "/api/rpc",
+        tag: "RPC",
+        summary: "Supen JSON-RPC control endpoint",
+        body: {
+            required: true,
+            schema: {
+                type: "object",
+                properties: {
+                    jsonrpc: { type: "string", enum: ["2.0"] },
+                    id: { oneOf: [{ type: "string" }, { type: "number" }, { type: "null" }] },
+                    method: { type: "string" },
+                    params: { type: "object" },
+                },
+                required: ["jsonrpc", "method"],
+            },
+        },
+        response: "JSON-RPC response. WebSocket transport is available at /api/rpc/ws.",
+    },
+    {
+        method: "GET",
+        path: "/api/computer",
+        tag: "Computer",
+        summary: "Computer status and identity",
+    },
+    {
+        method: "POST",
+        path: "/api/computer/trust",
+        tag: "Computer",
+        summary: "Deprecated direct trust elevation",
+    },
+    {
+        method: "GET",
+        path: "/api/computer/models",
+        tag: "Computer",
+        summary: "List available LLM models",
+    },
+    {
+        method: "GET",
+        path: "/api/computer/codex/subscription",
+        tag: "Computer",
+        summary: "Read Codex subscription plan and usage from the app-server",
+    },
+    {
+        method: "GET",
+        path: "/api/computer/usage",
+        tag: "Computer",
+        summary: "Get global token and cost usage totals",
+    },
+    {
+        method: "GET",
+        path: "/api/computer/usage/daily",
+        tag: "Computer",
+        summary: "Get daily usage ledger",
+    },
+    {
+        method: "POST",
+        path: "/api/computer/config/reload",
+        tag: "Computer",
+        summary: "Reload computer runtime config (models/providers) without restart",
+    },
+    // ── Agents ──────────────────────────────────────────────────────────────
+    {
+        method: "GET",
+        path: "/api/computer/agents",
+        tag: "Agents",
+        summary: "List agents",
+    },
+    {
+        method: "POST",
+        path: "/api/computer/agents",
+        tag: "Agents",
+        summary: "Create agent",
+        body: {
+            required: true,
+            schema: {
+                type: "object",
+                required: ["id"],
+                properties: {
+                    id: { type: "string" },
+                    name: { type: "string" },
+                    description: { type: "string" },
+                },
+            },
+        },
+    },
+    {
+        method: "GET",
+        path: "/api/computer/agents/{agent_id}",
+        tag: "Agents",
+        summary: "Get agent config",
+        params: [agentId],
+    },
+    {
+        method: "PATCH",
+        path: "/api/computer/agents/{agent_id}",
+        tag: "Agents",
+        summary: "Update agent config",
+        params: [agentId],
+        body: { required: true, schema: { type: "object" } },
+    },
+    {
+        method: "DELETE",
+        path: "/api/computer/agents/{agent_id}",
+        tag: "Agents",
+        summary: "Delete agent",
+        params: [agentId],
+    },
+    {
+        method: "GET",
+        path: "/api/computer/agents/{agent_id}/mind",
+        tag: "Agents",
+        summary: "Get agent mind files",
+        params: [agentId],
+    },
+    {
+        method: "GET",
+        path: "/api/computer/agents/{agent_id}/artifacts",
+        tag: "Agents",
+        summary: "List agent artifacts",
+        params: [agentId],
+    },
+    {
+        method: "GET",
+        path: "/api/computer/agents/{agent_id}/memory",
+        tag: "Agents",
+        summary: "Get agent memory roll",
+        params: [agentId],
+    },
+    {
+        method: "PUT",
+        path: "/api/computer/agents/{agent_id}/memory/{memory_id}",
+        tag: "Agents",
+        summary: "Save agent memory entry",
+        params: [agentId, { name: "memory_id", in: "path", required: true, type: "string" }],
+        body: {
+            required: true,
+            schema: {
+                type: "object",
+                required: ["content"],
+                properties: { content: { type: "string" } },
+            },
+        },
+    },
+    {
+        method: "POST",
+        path: "/api/computer/agents/{agent_id}/workspace/upload",
+        tag: "Agents",
+        summary: "Upload file to workspace",
+        params: [agentId],
+    },
+    {
+        method: "DELETE",
+        path: "/api/computer/agents/{agent_id}/workspace/{path}",
+        tag: "Agents",
+        summary: "Delete workspace file or folder",
+        params: [agentId, { name: "path", in: "path", required: true, type: "string" }],
+    },
+    {
+        method: "POST",
+        path: "/api/computer/agents/{agent_id}/workspace/rename",
+        tag: "Agents",
+        summary: "Rename workspace file or folder",
+        params: [agentId],
+    },
+    {
+        method: "POST",
+        path: "/api/computer/agents/{agent_id}/workspace/mkdir",
+        tag: "Agents",
+        summary: "Create workspace folder",
+        params: [agentId],
+    },
+    // ── Sessions ─────────────────────────────────────────────────────────────
+    {
+        method: "GET",
+        path: "/api/computer/agents/{agent_id}/sessions",
+        tag: "Sessions",
+        summary: "List sessions",
+        params: [agentId],
+    },
+    {
+        method: "POST",
+        path: "/api/computer/agents/{agent_id}/sessions",
+        tag: "Sessions",
+        summary: "Create session",
+        params: [agentId],
+        body: {
+            schema: { type: "object", properties: { title: { type: "string" } } },
+        },
+    },
+    {
+        method: "GET",
+        path: "/api/computer/agents/{agent_id}/sessions/{session_id}",
+        tag: "Sessions",
+        summary: "Get session",
+        params: [agentId, sessionId],
+    },
+    {
+        method: "PATCH",
+        path: "/api/computer/agents/{agent_id}/sessions/{session_id}",
+        tag: "Sessions",
+        summary: "Update session title",
+        params: [agentId, sessionId],
+        body: {
+            required: true,
+            schema: { type: "object", properties: { title: { type: "string" } } },
+        },
+    },
+    {
+        method: "DELETE",
+        path: "/api/computer/agents/{agent_id}/sessions/{session_id}",
+        tag: "Sessions",
+        summary: "Delete session",
+        params: [agentId, sessionId],
+    },
+    {
+        method: "POST",
+        path: "/api/computer/agents/{agent_id}/threads/refresh-titles",
+        tag: "Threads",
+        summary: "Refresh thread titles from Codex metadata",
+        params: [agentId],
+        body: {
+            schema: { type: "object", properties: { force: { type: "boolean" } } },
+        },
+    },
+    {
+        method: "POST",
+        path: "/api/computer/agents/{agent_id}/threads/{thread_id}/refresh-title",
+        tag: "Threads",
+        summary: "Refresh one thread title from Codex metadata",
+        params: [agentId, threadId],
+        body: {
+            schema: { type: "object", properties: { force: { type: "boolean" } } },
+        },
+    },
+    {
+        method: "GET",
+        path: "/api/computer/agents/{agent_id}/sessions/{session_id}/messages",
+        tag: "Sessions",
+        summary: "Chat history",
+        params: [agentId, sessionId],
+    },
+    {
+        method: "POST",
+        path: "/api/computer/agents/{agent_id}/sessions/{session_id}/messages",
+        tag: "Sessions",
+        summary: "Append a stored user + assistant turn (e.g. web slash commands)",
+        params: [agentId, sessionId],
+        body: {
+            required: true,
+            schema: {
+                type: "object",
+                required: ["user_text", "assistant_text"],
+                properties: {
+                    user_text: { type: "string" },
+                    assistant_text: { type: "string" },
+                },
+            },
+        },
+    },
+    {
+        method: "GET",
+        path: "/api/computer/agents/{agent_id}/sessions/{session_id}/stream",
+        tag: "Sessions",
+        summary: "SSE stream",
+        description: "Real-time Server-Sent Events stream for agent responses. Use EventSource. Events: delta, done, error.",
+        params: [agentId, sessionId],
+        response: "text/event-stream",
+    },
+    // ── Skills ───────────────────────────────────────────────────────────────
+    {
+        method: "POST",
+        path: "/api/computer/agents/{agent_id}/sessions/{session_id}/chat",
+        tag: "Sessions",
+        summary: "Native chat stream",
+        params: [agentId, sessionId],
+        body: {
+            required: true,
+            schema: {
+                type: "object",
+                properties: {
+                    messages: { type: "array", items: { type: "object" } },
+                    model: { type: "string" },
+                },
+            },
+        },
+    },
+    {
+        method: "GET",
+        path: "/api/computer/skills",
+        tag: "Skills",
+        summary: "List skills",
+    },
+    {
+        method: "POST",
+        path: "/api/computer/skills/query",
+        tag: "Skills",
+        summary: "List skills with catalog refresh",
+        body: {
+            required: false,
+            schema: {
+                type: "object",
+                properties: {
+                    forceRefresh: { type: "boolean" },
+                    githubToken: { type: "string" },
+                    sources: { type: "array", items: { type: "object" } },
+                },
+            },
+        },
+    },
+    {
+        method: "GET",
+        path: "/api/computer/skills/{name}",
+        tag: "Skills",
+        summary: "Get skill details",
+        params: [skillName],
+    },
+    {
+        method: "POST",
+        path: "/api/computer/skills/{name}/enable",
+        tag: "Skills",
+        summary: "Enable skill",
+        params: [skillName],
+    },
+    {
+        method: "POST",
+        path: "/api/computer/skills/{name}/disable",
+        tag: "Skills",
+        summary: "Disable skill",
+        params: [skillName],
+    },
+    {
+        method: "POST",
+        path: "/api/computer/skills/upgrade-all",
+        tag: "Skills",
+        summary: "Upgrade all installed skills",
+        body: {
+            required: false,
+            schema: {
+                type: "object",
+                properties: {
+                    forceRefresh: { type: "boolean" },
+                    githubToken: { type: "string" },
+                    sources: { type: "array", items: { type: "object" } },
+                },
+            },
+        },
+    },
+    {
+        method: "POST",
+        path: "/api/computer/skills/{name}/upgrade",
+        tag: "Skills",
+        summary: "Upgrade one installed skill",
+        params: [skillName],
+    },
+    {
+        method: "POST",
+        path: "/api/computer/skills/install",
+        tag: "Skills",
+        summary: "Install dynamic skill by URL",
+        body: {
+            required: true,
+            schema: {
+                type: "object",
+                properties: { source: { type: "string" }, url: { type: "string" } },
+            },
+        },
+    },
+    {
+        method: "GET",
+        path: "/api/computer/plugins",
+        tag: "Plugins",
+        summary: "List plugins",
+    },
+    {
+        method: "POST",
+        path: "/api/computer/plugins/query",
+        tag: "Plugins",
+        summary: "List plugins with catalog refresh",
+        body: {
+            required: false,
+            schema: {
+                type: "object",
+                properties: {
+                    forceRefresh: { type: "boolean" },
+                    githubToken: { type: "string" },
+                    sources: { type: "array", items: { type: "object" } },
+                },
+            },
+        },
+    },
+    {
+        method: "POST",
+        path: "/api/computer/plugins/install",
+        tag: "Plugins",
+        summary: "Install plugin by name",
+        body: {
+            required: true,
+            schema: {
+                type: "object",
+                properties: {
+                    name: { type: "string" },
+                    forceRefresh: { type: "boolean" },
+                    githubToken: { type: "string" },
+                    sources: { type: "array", items: { type: "object" } },
+                },
+            },
+        },
+    },
+    {
+        method: "GET",
+        path: "/api/computer/plugins/{name}",
+        tag: "Plugins",
+        summary: "Get plugin details",
+        params: [skillName],
+    },
+    {
+        method: "POST",
+        path: "/api/computer/plugins/{name}/upgrade",
+        tag: "Plugins",
+        summary: "Upgrade one installed plugin",
+        params: [skillName],
+        body: {
+            schema: {
+                type: "object",
+                properties: {
+                    forceRefresh: { type: "boolean" },
+                    githubToken: { type: "string" },
+                    sources: { type: "array", items: { type: "object" } },
+                },
+            },
+        },
+    },
+    // ── Automations ──────────────────────────────────────────────────────────
+    {
+        method: "GET",
+        path: "/api/computer/automations",
+        tag: "Automations",
+        summary: "List automations",
+    },
+    {
+        method: "POST",
+        path: "/api/computer/automations",
+        tag: "Automations",
+        summary: "Create automation",
+        body: { required: true, schema: { type: "object" } },
+    },
+    {
+        method: "PATCH",
+        path: "/api/computer/automations/{id}",
+        tag: "Automations",
+        summary: "Update automation",
+        params: [automationId],
+        body: { required: true, schema: { type: "object" } },
+    },
+    {
+        method: "DELETE",
+        path: "/api/computer/automations/{id}",
+        tag: "Automations",
+        summary: "Delete automation",
+        params: [automationId],
+    },
+    {
+        method: "GET",
+        path: "/api/computer/automations/{id}/runs",
+        tag: "Automations",
+        summary: "List runs for automation",
+        params: [automationId],
+    },
+    {
+        method: "GET",
+        path: "/api/computer/automation-runs",
+        tag: "Automations",
+        summary: "List automation runs",
+    },
+    {
+        method: "POST",
+        path: "/api/computer/automations/refresh",
+        tag: "Automations",
+        summary: "Force automation check",
+    },
+    // ── Enrollment ───────────────────────────────────────────────────────────
+    {
+        method: "GET",
+        path: "/api/computer/enroll/status",
+        tag: "Enrollment",
+        summary: "Enrollment status",
+    },
+    {
+        method: "POST",
+        path: "/api/computer/enroll/token",
+        tag: "Enrollment",
+        summary: "Issue enrollment token",
+    },
+    {
+        method: "POST",
+        path: "/api/computer/enroll/verify",
+        tag: "Enrollment",
+        summary: "Verify enrollment token",
+    },
+    {
+        method: "POST",
+        path: "/api/computer/enroll/revoke",
+        tag: "Enrollment",
+        summary: "Revoke enrollment and mark daemon trust as revoked",
+    },
+];
+function deriveCanonicalPath(path) {
+    if (path === "/api/computer") {
+        return { path: "/api/computers/{computer_id}", needsComputerParam: true };
+    }
+    if (!path.startsWith("/api/computer/"))
+        return null;
+    const tail = path.slice("/api/computer".length);
+    if (!tail || tail === "/")
+        return null;
+    return { path: `/api/computers/{computer_id}${tail}`, needsComputerParam: true };
+}
+function withCanonicalComputerParam(op) {
+    const existing = Array.isArray(op.parameters)
+        ? op.parameters
+        : [];
+    const hasComputerParam = existing.some((item) => item?.in === "path" && item?.name === "computer_id");
+    if (hasComputerParam)
+        return { ...op };
+    return {
+        ...op,
+        parameters: [
+            {
+                name: computerId.name,
+                in: computerId.in,
+                required: computerId.required ?? true,
+                schema: { type: computerId.type ?? "string" },
+                ...(computerId.description ? { description: computerId.description } : {}),
+            },
+            ...existing,
+        ],
+    };
+}
+/** Build an OpenAPI 3.0 paths object from ROUTES. */
+export function buildDaemonPaths() {
+    const paths = {};
+    for (const route of ROUTES) {
+        const op = {
+            tags: [route.tag],
+            summary: route.summary,
+        };
+        if (route.description)
+            op.description = route.description;
+        const parameters = (route.params ?? []).map((p) => ({
+            name: p.name,
+            in: p.in,
+            required: p.required ?? true,
+            schema: { type: p.type ?? "string" },
+            ...(p.description ? { description: p.description } : {}),
+        }));
+        if (parameters.length)
+            op.parameters = parameters;
+        if (route.body) {
+            op.requestBody = {
+                required: route.body.required ?? false,
+                content: { "application/json": { schema: route.body.schema } },
+            };
+        }
+        const responseContent = route.response === "text/event-stream"
+            ? { "text/event-stream": { schema: { type: "string" } } }
+            : {
+                "application/json": {
+                    schema: route.responseSchema ?? { type: "object" },
+                },
+            };
+        op.responses = { "200": { description: "OK", content: responseContent } };
+        const methodKey = route.method.toLowerCase();
+        const canonical = deriveCanonicalPath(route.path);
+        const documentedPath = canonical?.path ?? route.path;
+        const documentedOp = canonical?.needsComputerParam
+            ? withCanonicalComputerParam({ ...op, "x-internal-path": route.path })
+            : canonical
+                ? { ...op, "x-internal-path": route.path }
+                : op;
+        if (!paths[documentedPath])
+            paths[documentedPath] = {};
+        paths[documentedPath][methodKey] = documentedOp;
+    }
+    return paths;
+}
+/** Full OpenAPI spec for the daemon's HTTP API. */
+export function buildDaemonOpenApiSpec(opts = {}) {
+    const defaultOrigin = opts.serverUrl || "http://localhost:2756";
+    const parsedDefaultOrigin = new URL(defaultOrigin);
+    const defaultScheme = parsedDefaultOrigin.protocol.replace(/:$/, "");
+    const defaultHost = parsedDefaultOrigin.host;
+    return {
+        openapi: "3.0.3",
+        info: {
+            title: "Supen Daemon API",
+            version: "1.0.0",
+            description: "HTTP API served by a Supen Daemon. Normally accessed via the Gateway relay.",
+        },
+        servers: [
+            {
+                url: "{scheme}://{host}",
+                description: "Supen target origin",
+                variables: {
+                    scheme: {
+                        default: defaultScheme,
+                        description: "Protocol for the target Supen API origin, e.g. https or http",
+                    },
+                    host: {
+                        default: defaultHost,
+                        description: "Host and optional port for the target Supen API origin, e.g. supen.example.com or localhost:2756",
+                    },
+                },
+            },
+        ],
+        security: [{ apiKey: [] }],
+        components: {
+            securitySchemes: {
+                apiKey: {
+                    type: "apiKey",
+                    in: "header",
+                    name: "X-API-Key",
+                    description: "Set via HTTP_API_KEY env var on the daemon.",
+                },
+            },
+        },
+        paths: buildDaemonPaths(),
+    };
+}
+//# sourceMappingURL=http-routes.js.map