@solidxai/core-ui 0.1.19-beta.0 → 0.1.19

package/dist/components/core/solid-agent/embed/agentEmbedProtocol.ts

@@ -0,0 +1,60 @@
+import type { AgentBootstrap } from "../client/agentAuth";
+
+export const EMBED_CHANNEL = "solidx-agent-embed";
+export type AgentInputDefinition = { name: string; description: string; dataType: string };
+export type AgentEmbedBootstrap = AgentBootstrap & {
+    embed: true;
+    agentId: number;
+    title?: string;
+    requiredInputs: AgentInputDefinition[];
+};
+
+export class MissingAgentInputsError extends Error {
+    constructor(readonly inputNames: string[]) {
+        super(`Required inputs are missing: ${inputNames.join(", ")}`);
+        this.name = "MissingAgentInputsError";
+    }
+}
+
+export function validateBootstrap(value: unknown, agentId: number): AgentEmbedBootstrap {
+    const body = value as AgentEmbedBootstrap;
+    if (!body || body.embed !== true || body.agentId !== agentId || typeof body.agentToken !== "string" || !body.agentToken
+        || !Array.isArray(body.requiredInputs)) throw new Error("The token endpoint returned an invalid embed response.");
+    const ws = new URL(body.wsUrl), http = new URL(body.httpUrl);
+    if (!["ws:", "wss:"].includes(ws.protocol) || !["http:", "https:"].includes(http.protocol)
+        || ws.username || ws.password || http.username || http.password || ws.search || http.search || ws.hash || http.hash)
+        throw new Error("The token endpoint returned invalid connection URLs.");
+    if (window.location.protocol === "https:" && (ws.protocol !== "wss:" || http.protocol !== "https:"))
+        throw new Error("HTTPS embeds require HTTPS and WSS AgentHub endpoints.");
+    return body;
+}
+
+export function validateEmbedInputs(fields: AgentInputDefinition[], suppliedValues?: Record<string, unknown>): void {
+    const values = suppliedValues ?? {};
+    if (typeof values !== "object" || Array.isArray(values)) throw new Error("inputs must be an object.");
+    const names = new Set(fields.map((field) => field.name));
+    for (const name of Object.keys(values)) if (!names.has(name)) throw new Error(`Unknown input: ${name}`);
+    const missing = fields
+        .filter(({ name }) => {
+            const value = values[name];
+            return value === undefined || value === null || (typeof value === "string" && !value.trim());
+        })
+        .map(({ name }) => name);
+    if (missing.length) throw new MissingAgentInputsError(missing);
+    for (const field of fields) {
+        const value = values[field.name];
+        let valid = false;
+        switch (field.dataType) {
+            case "string": valid = typeof value === "string"; break;
+            case "number": valid = typeof value === "number" && Number.isFinite(value); break;
+            case "integer": valid = typeof value === "number" && Number.isSafeInteger(value); break;
+            case "boolean": valid = typeof value === "boolean"; break;
+            case "array": valid = Array.isArray(value); break;
+            case "object": valid = typeof value === "object" && value !== null && !Array.isArray(value); break;
+            case "date": valid = typeof value === "string" && /^\d{4}-\d{2}-\d{2}$/.test(value)
+                && !Number.isNaN(Date.parse(value)) && new Date(value).toISOString().slice(0, 10) === value; break;
+            case "datetime": valid = typeof value === "string" && /^\d{4}-\d{2}-\d{2}T/.test(value) && !Number.isNaN(Date.parse(value)); break;
+        }
+        if (!valid) throw new Error(`Input ${field.name} must have data type ${field.dataType}.`);
+    }
+}

package/dist/components/core/solid-agent/embed/agentEmbedSamples.d.ts

@@ -0,0 +1,11 @@
+import type { AgentInputDefinition } from "./agentEmbedProtocol";
+export declare function embedSamples(agentId: number, fields: AgentInputDefinition[], sdkUrl: string, hubBase: string): {
+    javascript: string;
+    react: string;
+    python: string;
+    nestjs: string;
+    express: string;
+    java: string;
+    dotnet: string;
+};
+//# sourceMappingURL=agentEmbedSamples.d.ts.map

package/dist/components/core/solid-agent/embed/agentEmbedSamples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentEmbedSamples.d.ts","sourceRoot":"","sources":["../../../../../src/components/core/solid-agent/embed/agentEmbedSamples.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAMjE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;;;;;;;;EAmQ5G"}

package/dist/components/core/solid-agent/embed/agentEmbedSamples.js

@@ -0,0 +1,21 @@
+var js = function (value) { return JSON.stringify(value, null, 2).replace(/</g, "\\u003c").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029"); };
+var examples = { string: "Replace with your value", number: 0, integer: 0, boolean: false,
+    date: "2026-01-01", datetime: "2026-01-01T09:00:00Z", object: {}, array: [] };
+export function embedSamples(agentId, fields, sdkUrl, hubBase) {
+    var values = Object.fromEntries(fields.map(function (field) { var _a; return [field.name, (_a = examples[field.dataType]) !== null && _a !== void 0 ? _a : "Replace with your value"]; }));
+    var valuesJson = js(values).replace(/\n/g, "\n    ");
+    var backendUrl = hubBase.replace(/\/$/, "");
+    var environmentNote = "# AGENTHUB_BACKEND_URL=".concat(backendUrl);
+    var environmentNoteSlash = "// AGENTHUB_BACKEND_URL=".concat(backendUrl);
+    var config = "agentId: ".concat(agentId, ",\n    tokenEndpoint: \"/api/agent-chat/token\",\n    inputs: ").concat(valuesJson);
+    return {
+        javascript: "<div id=\"agent-chat\"></div>\n<script src=".concat(JSON.stringify(sdkUrl).replace(/</g, "&lt;"), "></script>\n<script>\n  // Values should come from the current page or trusted app state.\n  // The API key and AgentHub URL stay on your server.\n  const chat = SolidAgentEmbed.mount({\n    container: \"#agent-chat\",\n    ").concat(config, "\n  });\n  // For app auth/CSRF, add getTokenHeaders: () => yourAppAuthHeaders().\n  // Optional lifecycle methods: chat.open(), chat.close(), chat.destroy().\n  // Update context before the first message or after starting a new chat:\n  // await chat.setInputs({ ... });\n</script>"),
+        react: "\"use client\";\nimport { useEffect, useRef } from \"react\";\n\ntype AgentEmbed = { destroy: () => void };\ntype AgentEmbedSdk = { mount: (options: {\n  container: HTMLElement; agentId: number; tokenEndpoint: string;\n  inputs: Record<string, unknown>; label?: string; title?: string;\n  getTokenHeaders?: () => Record<string, string>;\n}) => AgentEmbed };\ndeclare global { interface Window { SolidAgentEmbed?: AgentEmbedSdk } }\n\nconst SDK_URL = ".concat(js(sdkUrl), ";\nlet sdkPromise: Promise<AgentEmbedSdk> | undefined;\nfunction loadSdk() {\n  if (window.SolidAgentEmbed) return Promise.resolve(window.SolidAgentEmbed);\n  if (!sdkPromise) sdkPromise = new Promise((resolve, reject) => {\n    const script = document.createElement(\"script\");\n    script.src = SDK_URL;\n    script.async = true;\n    script.onload = () => window.SolidAgentEmbed\n      ? resolve(window.SolidAgentEmbed)\n      : reject(new Error(\"Agent embed SDK did not initialize\"));\n    script.onerror = () => { script.remove(); sdkPromise = undefined; reject(new Error(\"Could not load Agent embed SDK\")); };\n    document.head.appendChild(script);\n  });\n  return sdkPromise;\n}\n\nexport function AgentChat() {\n  const containerRef = useRef<HTMLDivElement>(null);\n  useEffect(() => {\n    let disposed = false;\n    let chat: AgentEmbed | undefined;\n    void loadSdk().then((sdk) => {\n      if (disposed || !containerRef.current) return;\n      chat = sdk.mount({\n        container: containerRef.current,\n        ").concat(config.replace(/\n/g, "\n        "), "\n      });\n    }).catch((error: unknown) => {\n      if (!disposed) console.error(\"Could not initialize agent chat\", error);\n    });\n    return () => { disposed = true; chat?.destroy(); };\n  }, []);\n  return <div ref={containerRef} />;\n}"),
+        python: "# FastAPI. Install httpx; mount this router in your application.\n# Keep these server-only environment variables out of the browser bundle:\n# AGENTHUB_API_KEY, AGENTHUB_AGENT_ID, AGENTHUB_BACKEND_URL\n".concat(environmentNote, "\nimport os\nimport httpx\nfrom fastapi import APIRouter, HTTPException, Request, Response\nfrom pydantic import BaseModel\n\nrouter = APIRouter()\nAGENTHUB_URL = (os.getenv(\"AGENTHUB_BACKEND_URL\") or \"\").rstrip(\"/\")\n\nclass TokenRequest(BaseModel):\n    agentId: int\n\n@router.post(\"/api/agent-chat/token\")\nasync def create_agent_token(body: TokenRequest, request: Request, response: Response):\n    response.headers[\"Cache-Control\"] = \"no-store\"\n    try:\n        agent_id = int(os.environ.get(\"AGENTHUB_AGENT_ID\", \"0\"))\n    except ValueError:\n        agent_id = 0\n    api_key = os.getenv(\"AGENTHUB_API_KEY\")\n    if not api_key or not AGENTHUB_URL or agent_id <= 0:\n        raise HTTPException(status_code=503, detail=\"Chat is temporarily unavailable\")\n    if body.agentId != agent_id:\n        raise HTTPException(status_code=400, detail=\"Agent is not configured for this application\")\n    # If trusted optional-auth middleware populated request.state.user, pass its stable ID.\n    user = getattr(request.state, \"user\", None)\n    external_id = user.get(\"id\") if isinstance(user, dict) else getattr(user, \"id\", None)\n    payload = {\"apiKey\": api_key, \"agentId\": agent_id}\n    if external_id is not None:\n        payload[\"externalUserId\"] = f\"my-app:{external_id}\"\n    try:\n        async with httpx.AsyncClient(timeout=15) as client:\n            upstream = await client.post(f\"{AGENTHUB_URL}/api/agent/api-keys/embedded/me\", json=payload)\n        if not upstream.is_success:\n            raise HTTPException(status_code=502, detail=\"Chat is temporarily unavailable\")\n        return upstream.json()  # forward the token response; never cache or log it\n    except httpx.HTTPError as exc:\n        raise HTTPException(status_code=503, detail=\"Chat is temporarily unavailable\") from exc\n"),
+        nestjs: "// NestJS. Uses the app's existing ConfigService and optional auth middleware.\n// Add a distributed rate limit at the gateway or with your Nest throttler.\nimport { Body, Controller, HttpException, HttpStatus, Post, Req, Res } from \"@nestjs/common\";\nimport { ConfigService } from \"@nestjs/config\";\nimport { Public } from \"@solidxai/core\";\nimport { Request, Response } from \"express\";\n\n// Server environment: AGENTHUB_API_KEY=...; AGENTHUB_AGENT_ID=".concat(agentId, "\n").concat(environmentNoteSlash, "\ntype EmbedRequest = Request & { user?: { id?: string | number; sub?: string | number } };\n@Controller(\"agent-chat\")\nexport class AgentChatController {\n  constructor(private readonly config: ConfigService) {}\n\n  @Post(\"token\")\n  @Public() // allow anonymous use; remove/replace with your app policy for login-only chat\n  async createToken(@Body() body: { agentId: number }, @Req() req: EmbedRequest, @Res() res: Response) {\n    res.setHeader(\"Cache-Control\", \"no-store\");\n    const agentId = Number(this.config.get(\"AGENTHUB_AGENT_ID\")); // fixed; never trust browser selection\n    const apiKey = this.config.get<string>(\"AGENTHUB_API_KEY\");\n    const baseUrl = this.config.get<string>(\"AGENTHUB_BACKEND_URL\")?.replace(/\\/$/, \"\");\n    if (!apiKey || !baseUrl || !Number.isSafeInteger(agentId) || agentId <= 0)\n      throw new HttpException(\"Chat is temporarily unavailable\", HttpStatus.SERVICE_UNAVAILABLE);\n    if (body.agentId !== agentId) throw new HttpException(\"Agent is not configured\", HttpStatus.BAD_REQUEST);\n    const userId = req.user?.id ?? req.user?.sub; // set only by trusted auth middleware\n    const payload = { apiKey, agentId, ...(userId != null ? { externalUserId: \"my-app:\" + userId } : {}) };\n    try {\n      const upstream = await fetch(baseUrl + \"/api/agent/api-keys/embedded/me\", {\n        method: \"POST\", headers: { \"Content-Type\": \"application/json\" },\n        body: JSON.stringify(payload), signal: AbortSignal.timeout(15_000),\n      });\n      if (!upstream.ok) throw new HttpException(\"Chat is temporarily unavailable\", HttpStatus.BAD_GATEWAY);\n      res.status(200).type(\"application/json\").send(await upstream.text());\n    } catch (error) {\n      if (error instanceof HttpException) throw error;\n      throw new HttpException(\"Chat is temporarily unavailable\", HttpStatus.SERVICE_UNAVAILABLE);\n    }\n  }\n}\n// Mount behind trusted proxy configuration and rate limiting. Apply the app's\n// authentication/authorization guard instead of @Public() when access is restricted."),
+        express: "// Express (Node.js 20+). Mount after any optional authentication middleware.\n// Protect this public endpoint with a distributed/IP-aware rate limiter in production.\n// Server environment: AGENTHUB_API_KEY=...; AGENTHUB_AGENT_ID=".concat(agentId, "\n").concat(environmentNoteSlash, "\nimport express from \"express\";\n\nconst router = express.Router();\nrouter.post(\"/api/agent-chat/token\", async (req, res) => {\n  res.set(\"Cache-Control\", \"no-store\");\n  const agentId = Number(process.env.AGENTHUB_AGENT_ID); // fixed server-side allowlist\n  const apiKey = process.env.AGENTHUB_API_KEY;\n  const baseUrl = process.env.AGENTHUB_BACKEND_URL?.replace(/\\/$/, \"\");\n  if (!apiKey || !baseUrl || !Number.isSafeInteger(agentId) || agentId <= 0)\n    return res.status(503).json({ error: \"Chat is temporarily unavailable\" });\n  if (Number(req.body?.agentId) !== agentId)\n    return res.status(400).json({ error: \"Agent is not configured for this application\" });\n  const userId = req.user?.id ?? req.user?.sub; // optional identity from trusted middleware\n  try {\n    const upstream = await fetch(baseUrl + \"/api/agent/api-keys/embedded/me\", {\n      method: \"POST\", headers: { \"Content-Type\": \"application/json\" },\n      body: JSON.stringify({ apiKey, agentId, ...(userId != null ? { externalUserId: \"my-app:\" + userId } : {}) }),\n      signal: AbortSignal.timeout(15_000),\n    });\n    if (!upstream.ok) return res.status(502).json({ error: \"Chat is temporarily unavailable\" });\n    return res.status(200).type(\"application/json\").send(await upstream.text());\n  } catch {\n    return res.status(503).json({ error: \"Chat is temporarily unavailable\" });\n  }\n});\nexport default router;\n// Ensure express.json() is installed. Never accept API key/backend URL from req.body."),
+        java: "// Spring Boot 3 / Java 17+. Keep this route public for anonymous embeds,\n// or apply your application's authorization policy. Add a distributed rate limiter.\n// Server environment: AGENTHUB_API_KEY=...; AGENTHUB_AGENT_ID=".concat(agentId, "\n").concat(environmentNoteSlash, "\n@RestController\npublic class AgentEmbedController {\n  private final java.net.http.HttpClient client = java.net.http.HttpClient.newBuilder()\n      .connectTimeout(java.time.Duration.ofSeconds(5)).build();\n  private final com.fasterxml.jackson.databind.ObjectMapper json = new com.fasterxml.jackson.databind.ObjectMapper();\n\n  @Value(\"${AGENTHUB_API_KEY}\") private String apiKey;\n  @Value(\"${AGENTHUB_AGENT_ID}\") private int agentId;\n  @Value(\"${AGENTHUB_BACKEND_URL}\") private String agentHubUrl;\n\n  @PostMapping(\"/api/agent-chat/token\")\n  public ResponseEntity<String> token(@RequestBody Map<String, Object> request,\n                                      org.springframework.security.core.Authentication authentication) throws Exception {\n    if (!Integer.valueOf(agentId).equals(request.get(\"agentId\")))\n      return ResponseEntity.badRequest().cacheControl(CacheControl.noStore()).build();\n    Map<String, Object> payload = new java.util.HashMap<>();\n    payload.put(\"apiKey\", apiKey); payload.put(\"agentId\", agentId);\n    // Omit externalUserId for anonymous access; ignore anonymous security principals.\n    if (authentication != null && authentication.isAuthenticated() &&\n        !(authentication instanceof org.springframework.security.authentication.AnonymousAuthenticationToken))\n      payload.put(\"externalUserId\", \"my-app:\" + authentication.getName());\n    var upstreamRequest = java.net.http.HttpRequest.newBuilder()\n        .uri(java.net.URI.create(agentHubUrl.replaceAll(\"/+$\", \"\") + \"/api/agent/api-keys/embedded/me\"))\n        .timeout(java.time.Duration.ofSeconds(15)).header(\"Content-Type\", \"application/json\")\n        .POST(java.net.http.HttpRequest.BodyPublishers.ofString(json.writeValueAsString(payload))).build();\n    try {\n      var upstream = client.send(upstreamRequest, java.net.http.HttpResponse.BodyHandlers.ofString());\n      if (upstream.statusCode() != 200)\n        return ResponseEntity.status(502).cacheControl(CacheControl.noStore()).build();\n      return ResponseEntity.ok().cacheControl(CacheControl.noStore())\n          .contentType(MediaType.APPLICATION_JSON).body(upstream.body());\n    } catch (java.io.IOException | InterruptedException error) {\n      if (error instanceof InterruptedException) Thread.currentThread().interrupt();\n      return ResponseEntity.status(503).cacheControl(CacheControl.noStore()).build();\n    }\n  }\n}\n// Imports: org.springframework.beans.factory.annotation.Value, web.bind.annotation.*,\n// org.springframework.http.*, java.util.Map. Do not log the key or token response."),
+        dotnet: "// ASP.NET Core Minimal API. Configure an IP/user rate-limit policy in production.\n// Authentication can be optional (anonymous demo) or required by your app's policy.\n// Server environment: AGENTHUB_API_KEY=...; AGENTHUB_AGENT_ID=".concat(agentId, "\n").concat(environmentNoteSlash, "\nusing System.Security.Claims;\nusing System.Collections.Generic;\nusing System.Net.Http.Json;\n\nbuilder.Services.AddHttpClient(\"AgentHub\", client => client.Timeout = TimeSpan.FromSeconds(15));\napp.MapPost(\"/api/agent-chat/token\", async (AgentTokenRequest body, HttpContext context, IHttpClientFactory clients, IConfiguration config) => {\n    context.Response.Headers.CacheControl = \"no-store\";\n    if (!int.TryParse(config[\"AGENTHUB_AGENT_ID\"], out var agentId) || agentId <= 0)\n        return Results.StatusCode(503);\n    var apiKey = config[\"AGENTHUB_API_KEY\"];\n    var baseUrl = config[\"AGENTHUB_BACKEND_URL\"]?.TrimEnd('/');\n    if (string.IsNullOrWhiteSpace(apiKey) || string.IsNullOrWhiteSpace(baseUrl))\n        return Results.StatusCode(503);\n    if (body.AgentId != agentId)\n        return Results.BadRequest(new { error = \"Agent is not configured for this application\" });\n    var subject = context.User.FindFirst(ClaimTypes.NameIdentifier)?.Value;\n    var payload = new Dictionary<string, object?> { [\"apiKey\"] = apiKey, [\"agentId\"] = agentId };\n    if (context.User.Identity?.IsAuthenticated == true && !string.IsNullOrEmpty(subject))\n        payload[\"externalUserId\"] = \"my-app:\" + subject;\n    try {\n        var upstream = await clients.CreateClient(\"AgentHub\").PostAsJsonAsync(\n            baseUrl + \"/api/agent/api-keys/embedded/me\", payload, context.RequestAborted);\n        if (!upstream.IsSuccessStatusCode) return Results.StatusCode(502);\n        return Results.Text(await upstream.Content.ReadAsStringAsync(context.RequestAborted), \"application/json\");\n    } catch (HttpRequestException) { return Results.StatusCode(503); }\n}).AllowAnonymous(); // Replace with .RequireAuthorization() for login-only chat.\npublic sealed record AgentTokenRequest(int AgentId);\n// Imports: Microsoft.AspNetCore.Http, System.Net.Http.Json, System.Collections.Generic.\n// Add a distributed rate limiter and trusted-proxy configuration for public deployments."),
+    };
+}
+//# sourceMappingURL=agentEmbedSamples.js.map

package/dist/components/core/solid-agent/embed/agentEmbedSamples.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentEmbedSamples.js","sourceRoot":"","sources":["../../../../../src/components/core/solid-agent/embed/agentEmbedSamples.ts"],"names":[],"mappings":"AAEA,IAAM,EAAE,GAAG,UAAC,KAAc,IAAK,OAAA,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,EAAnH,CAAmH,CAAC;AACnJ,IAAM,QAAQ,GAA4B,EAAE,MAAM,EAAE,yBAAyB,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK;IAChH,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,sBAAsB,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;AAElF,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,MAA8B,EAAE,MAAc,EAAE,OAAe;IACzG,IAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,UAAC,KAAK,YAAK,OAAA,CAAC,KAAK,CAAC,IAAI,EAAE,MAAA,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,mCAAI,yBAAyB,CAAC,CAAA,EAAA,CAAC,CAAC,CAAC;IAC9H,IAAM,UAAU,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACvD,IAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC9C,IAAM,eAAe,GAAG,iCAA0B,UAAU,CAAE,CAAC;IAC/D,IAAM,oBAAoB,GAAG,kCAA2B,UAAU,CAAE,CAAC;IACrE,IAAM,MAAM,GAAG,mBAAY,OAAO,2EAA+D,UAAU,CAAE,CAAC;IAC9G,OAAO;QACH,UAAU,EAAE,qDACN,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,6OAMpD,MAAM,+RAMF;QACF,KAAK,EAAE,4cAWG,EAAE,CAAC,MAAM,CAAC,uhCA0BlB,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,YAAY,CAAC,2PAQ3C;QACM,MAAM,EAAE,oNAGd,eAAe,8zDAsChB;QACO,MAAM,EAAE,wdAOiD,OAAO,eACtE,oBAAoB,2hEAgCgE;QAC9E,OAAO,EAAE,iPAEgD,OAAO,eACtE,oBAAoB,6/CA2BiE;QAC/E,IAAI,EAAE,0OAEmD,OAAO,eACtE,oBAAoB,ojFAuC8D;QAC5E,MAAM,EAAE,mPAEiD,OAAO,eACtE,oBAAoB,g+DA6BoE;KACrF,CAAC;AACN,CAAC","sourcesContent":["import type { AgentInputDefinition } from \"./agentEmbedProtocol\";\n\nconst js = (value: unknown) => JSON.stringify(value, null, 2).replace(/</g, \"\\\\u003c\").replace(/\\u2028/g, \"\\\\u2028\").replace(/\\u2029/g, \"\\\\u2029\");\nconst examples: Record<string, unknown> = { string: \"Replace with your value\", number: 0, integer: 0, boolean: false,\n    date: \"2026-01-01\", datetime: \"2026-01-01T09:00:00Z\", object: {}, array: [] };\n\nexport function embedSamples(agentId: number, fields: AgentInputDefinition[], sdkUrl: string, hubBase: string) {\n    const values = Object.fromEntries(fields.map((field) => [field.name, examples[field.dataType] ?? \"Replace with your value\"]));\n    const valuesJson = js(values).replace(/\\n/g, \"\\n    \");\n    const backendUrl = hubBase.replace(/\\/$/, \"\");\n    const environmentNote = `# AGENTHUB_BACKEND_URL=${backendUrl}`;\n    const environmentNoteSlash = `// AGENTHUB_BACKEND_URL=${backendUrl}`;\n    const config = `agentId: ${agentId},\\n    tokenEndpoint: \"/api/agent-chat/token\",\\n    inputs: ${valuesJson}`;\n    return {\n        javascript: `<div id=\"agent-chat\"></div>\n<script src=${JSON.stringify(sdkUrl).replace(/</g, \"&lt;\")}></script>\n<script>\n  // Values should come from the current page or trusted app state.\n  // The API key and AgentHub URL stay on your server.\n  const chat = SolidAgentEmbed.mount({\n    container: \"#agent-chat\",\n    ${config}\n  });\n  // For app auth/CSRF, add getTokenHeaders: () => yourAppAuthHeaders().\n  // Optional lifecycle methods: chat.open(), chat.close(), chat.destroy().\n  // Update context before the first message or after starting a new chat:\n  // await chat.setInputs({ ... });\n</script>`,\n        react: `\"use client\";\nimport { useEffect, useRef } from \"react\";\n\ntype AgentEmbed = { destroy: () => void };\ntype AgentEmbedSdk = { mount: (options: {\n  container: HTMLElement; agentId: number; tokenEndpoint: string;\n  inputs: Record<string, unknown>; label?: string; title?: string;\n  getTokenHeaders?: () => Record<string, string>;\n}) => AgentEmbed };\ndeclare global { interface Window { SolidAgentEmbed?: AgentEmbedSdk } }\n\nconst SDK_URL = ${js(sdkUrl)};\nlet sdkPromise: Promise<AgentEmbedSdk> | undefined;\nfunction loadSdk() {\n  if (window.SolidAgentEmbed) return Promise.resolve(window.SolidAgentEmbed);\n  if (!sdkPromise) sdkPromise = new Promise((resolve, reject) => {\n    const script = document.createElement(\"script\");\n    script.src = SDK_URL;\n    script.async = true;\n    script.onload = () => window.SolidAgentEmbed\n      ? resolve(window.SolidAgentEmbed)\n      : reject(new Error(\"Agent embed SDK did not initialize\"));\n    script.onerror = () => { script.remove(); sdkPromise = undefined; reject(new Error(\"Could not load Agent embed SDK\")); };\n    document.head.appendChild(script);\n  });\n  return sdkPromise;\n}\n\nexport function AgentChat() {\n  const containerRef = useRef<HTMLDivElement>(null);\n  useEffect(() => {\n    let disposed = false;\n    let chat: AgentEmbed | undefined;\n    void loadSdk().then((sdk) => {\n      if (disposed || !containerRef.current) return;\n      chat = sdk.mount({\n        container: containerRef.current,\n        ${config.replace(/\\n/g, \"\\n        \")}\n      });\n    }).catch((error: unknown) => {\n      if (!disposed) console.error(\"Could not initialize agent chat\", error);\n    });\n    return () => { disposed = true; chat?.destroy(); };\n  }, []);\n  return <div ref={containerRef} />;\n}`,\n        python: `# FastAPI. Install httpx; mount this router in your application.\n# Keep these server-only environment variables out of the browser bundle:\n# AGENTHUB_API_KEY, AGENTHUB_AGENT_ID, AGENTHUB_BACKEND_URL\n${environmentNote}\nimport os\nimport httpx\nfrom fastapi import APIRouter, HTTPException, Request, Response\nfrom pydantic import BaseModel\n\nrouter = APIRouter()\nAGENTHUB_URL = (os.getenv(\"AGENTHUB_BACKEND_URL\") or \"\").rstrip(\"/\")\n\nclass TokenRequest(BaseModel):\n    agentId: int\n\n@router.post(\"/api/agent-chat/token\")\nasync def create_agent_token(body: TokenRequest, request: Request, response: Response):\n    response.headers[\"Cache-Control\"] = \"no-store\"\n    try:\n        agent_id = int(os.environ.get(\"AGENTHUB_AGENT_ID\", \"0\"))\n    except ValueError:\n        agent_id = 0\n    api_key = os.getenv(\"AGENTHUB_API_KEY\")\n    if not api_key or not AGENTHUB_URL or agent_id <= 0:\n        raise HTTPException(status_code=503, detail=\"Chat is temporarily unavailable\")\n    if body.agentId != agent_id:\n        raise HTTPException(status_code=400, detail=\"Agent is not configured for this application\")\n    # If trusted optional-auth middleware populated request.state.user, pass its stable ID.\n    user = getattr(request.state, \"user\", None)\n    external_id = user.get(\"id\") if isinstance(user, dict) else getattr(user, \"id\", None)\n    payload = {\"apiKey\": api_key, \"agentId\": agent_id}\n    if external_id is not None:\n        payload[\"externalUserId\"] = f\"my-app:{external_id}\"\n    try:\n        async with httpx.AsyncClient(timeout=15) as client:\n            upstream = await client.post(f\"{AGENTHUB_URL}/api/agent/api-keys/embedded/me\", json=payload)\n        if not upstream.is_success:\n            raise HTTPException(status_code=502, detail=\"Chat is temporarily unavailable\")\n        return upstream.json()  # forward the token response; never cache or log it\n    except httpx.HTTPError as exc:\n        raise HTTPException(status_code=503, detail=\"Chat is temporarily unavailable\") from exc\n`,\n        nestjs: `// NestJS. Uses the app's existing ConfigService and optional auth middleware.\n// Add a distributed rate limit at the gateway or with your Nest throttler.\nimport { Body, Controller, HttpException, HttpStatus, Post, Req, Res } from \"@nestjs/common\";\nimport { ConfigService } from \"@nestjs/config\";\nimport { Public } from \"@solidxai/core\";\nimport { Request, Response } from \"express\";\n\n// Server environment: AGENTHUB_API_KEY=...; AGENTHUB_AGENT_ID=${agentId}\n${environmentNoteSlash}\ntype EmbedRequest = Request & { user?: { id?: string | number; sub?: string | number } };\n@Controller(\"agent-chat\")\nexport class AgentChatController {\n  constructor(private readonly config: ConfigService) {}\n\n  @Post(\"token\")\n  @Public() // allow anonymous use; remove/replace with your app policy for login-only chat\n  async createToken(@Body() body: { agentId: number }, @Req() req: EmbedRequest, @Res() res: Response) {\n    res.setHeader(\"Cache-Control\", \"no-store\");\n    const agentId = Number(this.config.get(\"AGENTHUB_AGENT_ID\")); // fixed; never trust browser selection\n    const apiKey = this.config.get<string>(\"AGENTHUB_API_KEY\");\n    const baseUrl = this.config.get<string>(\"AGENTHUB_BACKEND_URL\")?.replace(/\\\\/$/, \"\");\n    if (!apiKey || !baseUrl || !Number.isSafeInteger(agentId) || agentId <= 0)\n      throw new HttpException(\"Chat is temporarily unavailable\", HttpStatus.SERVICE_UNAVAILABLE);\n    if (body.agentId !== agentId) throw new HttpException(\"Agent is not configured\", HttpStatus.BAD_REQUEST);\n    const userId = req.user?.id ?? req.user?.sub; // set only by trusted auth middleware\n    const payload = { apiKey, agentId, ...(userId != null ? { externalUserId: \"my-app:\" + userId } : {}) };\n    try {\n      const upstream = await fetch(baseUrl + \"/api/agent/api-keys/embedded/me\", {\n        method: \"POST\", headers: { \"Content-Type\": \"application/json\" },\n        body: JSON.stringify(payload), signal: AbortSignal.timeout(15_000),\n      });\n      if (!upstream.ok) throw new HttpException(\"Chat is temporarily unavailable\", HttpStatus.BAD_GATEWAY);\n      res.status(200).type(\"application/json\").send(await upstream.text());\n    } catch (error) {\n      if (error instanceof HttpException) throw error;\n      throw new HttpException(\"Chat is temporarily unavailable\", HttpStatus.SERVICE_UNAVAILABLE);\n    }\n  }\n}\n// Mount behind trusted proxy configuration and rate limiting. Apply the app's\n// authentication/authorization guard instead of @Public() when access is restricted.`,\n        express: `// Express (Node.js 20+). Mount after any optional authentication middleware.\n// Protect this public endpoint with a distributed/IP-aware rate limiter in production.\n// Server environment: AGENTHUB_API_KEY=...; AGENTHUB_AGENT_ID=${agentId}\n${environmentNoteSlash}\nimport express from \"express\";\n\nconst router = express.Router();\nrouter.post(\"/api/agent-chat/token\", async (req, res) => {\n  res.set(\"Cache-Control\", \"no-store\");\n  const agentId = Number(process.env.AGENTHUB_AGENT_ID); // fixed server-side allowlist\n  const apiKey = process.env.AGENTHUB_API_KEY;\n  const baseUrl = process.env.AGENTHUB_BACKEND_URL?.replace(/\\\\/$/, \"\");\n  if (!apiKey || !baseUrl || !Number.isSafeInteger(agentId) || agentId <= 0)\n    return res.status(503).json({ error: \"Chat is temporarily unavailable\" });\n  if (Number(req.body?.agentId) !== agentId)\n    return res.status(400).json({ error: \"Agent is not configured for this application\" });\n  const userId = req.user?.id ?? req.user?.sub; // optional identity from trusted middleware\n  try {\n    const upstream = await fetch(baseUrl + \"/api/agent/api-keys/embedded/me\", {\n      method: \"POST\", headers: { \"Content-Type\": \"application/json\" },\n      body: JSON.stringify({ apiKey, agentId, ...(userId != null ? { externalUserId: \"my-app:\" + userId } : {}) }),\n      signal: AbortSignal.timeout(15_000),\n    });\n    if (!upstream.ok) return res.status(502).json({ error: \"Chat is temporarily unavailable\" });\n    return res.status(200).type(\"application/json\").send(await upstream.text());\n  } catch {\n    return res.status(503).json({ error: \"Chat is temporarily unavailable\" });\n  }\n});\nexport default router;\n// Ensure express.json() is installed. Never accept API key/backend URL from req.body.`,\n        java: `// Spring Boot 3 / Java 17+. Keep this route public for anonymous embeds,\n// or apply your application's authorization policy. Add a distributed rate limiter.\n// Server environment: AGENTHUB_API_KEY=...; AGENTHUB_AGENT_ID=${agentId}\n${environmentNoteSlash}\n@RestController\npublic class AgentEmbedController {\n  private final java.net.http.HttpClient client = java.net.http.HttpClient.newBuilder()\n      .connectTimeout(java.time.Duration.ofSeconds(5)).build();\n  private final com.fasterxml.jackson.databind.ObjectMapper json = new com.fasterxml.jackson.databind.ObjectMapper();\n\n  @Value(\"\\${AGENTHUB_API_KEY}\") private String apiKey;\n  @Value(\"\\${AGENTHUB_AGENT_ID}\") private int agentId;\n  @Value(\"\\${AGENTHUB_BACKEND_URL}\") private String agentHubUrl;\n\n  @PostMapping(\"/api/agent-chat/token\")\n  public ResponseEntity<String> token(@RequestBody Map<String, Object> request,\n                                      org.springframework.security.core.Authentication authentication) throws Exception {\n    if (!Integer.valueOf(agentId).equals(request.get(\"agentId\")))\n      return ResponseEntity.badRequest().cacheControl(CacheControl.noStore()).build();\n    Map<String, Object> payload = new java.util.HashMap<>();\n    payload.put(\"apiKey\", apiKey); payload.put(\"agentId\", agentId);\n    // Omit externalUserId for anonymous access; ignore anonymous security principals.\n    if (authentication != null && authentication.isAuthenticated() &&\n        !(authentication instanceof org.springframework.security.authentication.AnonymousAuthenticationToken))\n      payload.put(\"externalUserId\", \"my-app:\" + authentication.getName());\n    var upstreamRequest = java.net.http.HttpRequest.newBuilder()\n        .uri(java.net.URI.create(agentHubUrl.replaceAll(\"/+$\", \"\") + \"/api/agent/api-keys/embedded/me\"))\n        .timeout(java.time.Duration.ofSeconds(15)).header(\"Content-Type\", \"application/json\")\n        .POST(java.net.http.HttpRequest.BodyPublishers.ofString(json.writeValueAsString(payload))).build();\n    try {\n      var upstream = client.send(upstreamRequest, java.net.http.HttpResponse.BodyHandlers.ofString());\n      if (upstream.statusCode() != 200)\n        return ResponseEntity.status(502).cacheControl(CacheControl.noStore()).build();\n      return ResponseEntity.ok().cacheControl(CacheControl.noStore())\n          .contentType(MediaType.APPLICATION_JSON).body(upstream.body());\n    } catch (java.io.IOException | InterruptedException error) {\n      if (error instanceof InterruptedException) Thread.currentThread().interrupt();\n      return ResponseEntity.status(503).cacheControl(CacheControl.noStore()).build();\n    }\n  }\n}\n// Imports: org.springframework.beans.factory.annotation.Value, web.bind.annotation.*,\n// org.springframework.http.*, java.util.Map. Do not log the key or token response.`,\n        dotnet: `// ASP.NET Core Minimal API. Configure an IP/user rate-limit policy in production.\n// Authentication can be optional (anonymous demo) or required by your app's policy.\n// Server environment: AGENTHUB_API_KEY=...; AGENTHUB_AGENT_ID=${agentId}\n${environmentNoteSlash}\nusing System.Security.Claims;\nusing System.Collections.Generic;\nusing System.Net.Http.Json;\n\nbuilder.Services.AddHttpClient(\"AgentHub\", client => client.Timeout = TimeSpan.FromSeconds(15));\napp.MapPost(\"/api/agent-chat/token\", async (AgentTokenRequest body, HttpContext context, IHttpClientFactory clients, IConfiguration config) => {\n    context.Response.Headers.CacheControl = \"no-store\";\n    if (!int.TryParse(config[\"AGENTHUB_AGENT_ID\"], out var agentId) || agentId <= 0)\n        return Results.StatusCode(503);\n    var apiKey = config[\"AGENTHUB_API_KEY\"];\n    var baseUrl = config[\"AGENTHUB_BACKEND_URL\"]?.TrimEnd('/');\n    if (string.IsNullOrWhiteSpace(apiKey) || string.IsNullOrWhiteSpace(baseUrl))\n        return Results.StatusCode(503);\n    if (body.AgentId != agentId)\n        return Results.BadRequest(new { error = \"Agent is not configured for this application\" });\n    var subject = context.User.FindFirst(ClaimTypes.NameIdentifier)?.Value;\n    var payload = new Dictionary<string, object?> { [\"apiKey\"] = apiKey, [\"agentId\"] = agentId };\n    if (context.User.Identity?.IsAuthenticated == true && !string.IsNullOrEmpty(subject))\n        payload[\"externalUserId\"] = \"my-app:\" + subject;\n    try {\n        var upstream = await clients.CreateClient(\"AgentHub\").PostAsJsonAsync(\n            baseUrl + \"/api/agent/api-keys/embedded/me\", payload, context.RequestAborted);\n        if (!upstream.IsSuccessStatusCode) return Results.StatusCode(502);\n        return Results.Text(await upstream.Content.ReadAsStringAsync(context.RequestAborted), \"application/json\");\n    } catch (HttpRequestException) { return Results.StatusCode(503); }\n}).AllowAnonymous(); // Replace with .RequireAuthorization() for login-only chat.\npublic sealed record AgentTokenRequest(int AgentId);\n// Imports: Microsoft.AspNetCore.Http, System.Net.Http.Json, System.Collections.Generic.\n// Add a distributed rate limiter and trusted-proxy configuration for public deployments.`,\n    };\n}\n"]}

package/dist/components/core/solid-agent/embed/agentEmbedSamples.ts

@@ -0,0 +1,266 @@
+import type { AgentInputDefinition } from "./agentEmbedProtocol";
+
+const js = (value: unknown) => JSON.stringify(value, null, 2).replace(/</g, "\\u003c").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+const examples: Record<string, unknown> = { string: "Replace with your value", number: 0, integer: 0, boolean: false,
+    date: "2026-01-01", datetime: "2026-01-01T09:00:00Z", object: {}, array: [] };
+
+export function embedSamples(agentId: number, fields: AgentInputDefinition[], sdkUrl: string, hubBase: string) {
+    const values = Object.fromEntries(fields.map((field) => [field.name, examples[field.dataType] ?? "Replace with your value"]));
+    const valuesJson = js(values).replace(/\n/g, "\n    ");
+    const backendUrl = hubBase.replace(/\/$/, "");
+    const environmentNote = `# AGENTHUB_BACKEND_URL=${backendUrl}`;
+    const environmentNoteSlash = `// AGENTHUB_BACKEND_URL=${backendUrl}`;
+    const config = `agentId: ${agentId},\n    tokenEndpoint: "/api/agent-chat/token",\n    inputs: ${valuesJson}`;
+    return {
+        javascript: `<div id="agent-chat"></div>
+<script src=${JSON.stringify(sdkUrl).replace(/</g, "&lt;")}></script>
+<script>
+  // Values should come from the current page or trusted app state.
+  // The API key and AgentHub URL stay on your server.
+  const chat = SolidAgentEmbed.mount({
+    container: "#agent-chat",
+    ${config}
+  });
+  // For app auth/CSRF, add getTokenHeaders: () => yourAppAuthHeaders().
+  // Optional lifecycle methods: chat.open(), chat.close(), chat.destroy().
+  // Update context before the first message or after starting a new chat:
+  // await chat.setInputs({ ... });
+</script>`,
+        react: `"use client";
+import { useEffect, useRef } from "react";
+
+type AgentEmbed = { destroy: () => void };
+type AgentEmbedSdk = { mount: (options: {
+  container: HTMLElement; agentId: number; tokenEndpoint: string;
+  inputs: Record<string, unknown>; label?: string; title?: string;
+  getTokenHeaders?: () => Record<string, string>;
+}) => AgentEmbed };
+declare global { interface Window { SolidAgentEmbed?: AgentEmbedSdk } }
+
+const SDK_URL = ${js(sdkUrl)};
+let sdkPromise: Promise<AgentEmbedSdk> | undefined;
+function loadSdk() {
+  if (window.SolidAgentEmbed) return Promise.resolve(window.SolidAgentEmbed);
+  if (!sdkPromise) sdkPromise = new Promise((resolve, reject) => {
+    const script = document.createElement("script");
+    script.src = SDK_URL;
+    script.async = true;
+    script.onload = () => window.SolidAgentEmbed
+      ? resolve(window.SolidAgentEmbed)
+      : reject(new Error("Agent embed SDK did not initialize"));
+    script.onerror = () => { script.remove(); sdkPromise = undefined; reject(new Error("Could not load Agent embed SDK")); };
+    document.head.appendChild(script);
+  });
+  return sdkPromise;
+}
+
+export function AgentChat() {
+  const containerRef = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    let disposed = false;
+    let chat: AgentEmbed | undefined;
+    void loadSdk().then((sdk) => {
+      if (disposed || !containerRef.current) return;
+      chat = sdk.mount({
+        container: containerRef.current,
+        ${config.replace(/\n/g, "\n        ")}
+      });
+    }).catch((error: unknown) => {
+      if (!disposed) console.error("Could not initialize agent chat", error);
+    });
+    return () => { disposed = true; chat?.destroy(); };
+  }, []);
+  return <div ref={containerRef} />;
+}`,
+        python: `# FastAPI. Install httpx; mount this router in your application.
+# Keep these server-only environment variables out of the browser bundle:
+# AGENTHUB_API_KEY, AGENTHUB_AGENT_ID, AGENTHUB_BACKEND_URL
+${environmentNote}
+import os
+import httpx
+from fastapi import APIRouter, HTTPException, Request, Response
+from pydantic import BaseModel
+
+router = APIRouter()
+AGENTHUB_URL = (os.getenv("AGENTHUB_BACKEND_URL") or "").rstrip("/")
+
+class TokenRequest(BaseModel):
+    agentId: int
+
+@router.post("/api/agent-chat/token")
+async def create_agent_token(body: TokenRequest, request: Request, response: Response):
+    response.headers["Cache-Control"] = "no-store"
+    try:
+        agent_id = int(os.environ.get("AGENTHUB_AGENT_ID", "0"))
+    except ValueError:
+        agent_id = 0
+    api_key = os.getenv("AGENTHUB_API_KEY")
+    if not api_key or not AGENTHUB_URL or agent_id <= 0:
+        raise HTTPException(status_code=503, detail="Chat is temporarily unavailable")
+    if body.agentId != agent_id:
+        raise HTTPException(status_code=400, detail="Agent is not configured for this application")
+    # If trusted optional-auth middleware populated request.state.user, pass its stable ID.
+    user = getattr(request.state, "user", None)
+    external_id = user.get("id") if isinstance(user, dict) else getattr(user, "id", None)
+    payload = {"apiKey": api_key, "agentId": agent_id}
+    if external_id is not None:
+        payload["externalUserId"] = f"my-app:{external_id}"
+    try:
+        async with httpx.AsyncClient(timeout=15) as client:
+            upstream = await client.post(f"{AGENTHUB_URL}/api/agent/api-keys/embedded/me", json=payload)
+        if not upstream.is_success:
+            raise HTTPException(status_code=502, detail="Chat is temporarily unavailable")
+        return upstream.json()  # forward the token response; never cache or log it
+    except httpx.HTTPError as exc:
+        raise HTTPException(status_code=503, detail="Chat is temporarily unavailable") from exc
+`,
+        nestjs: `// NestJS. Uses the app's existing ConfigService and optional auth middleware.
+// Add a distributed rate limit at the gateway or with your Nest throttler.
+import { Body, Controller, HttpException, HttpStatus, Post, Req, Res } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { Public } from "@solidxai/core";
+import { Request, Response } from "express";
+
+// Server environment: AGENTHUB_API_KEY=...; AGENTHUB_AGENT_ID=${agentId}
+${environmentNoteSlash}
+type EmbedRequest = Request & { user?: { id?: string | number; sub?: string | number } };
+@Controller("agent-chat")
+export class AgentChatController {
+  constructor(private readonly config: ConfigService) {}
+
+  @Post("token")
+  @Public() // allow anonymous use; remove/replace with your app policy for login-only chat
+  async createToken(@Body() body: { agentId: number }, @Req() req: EmbedRequest, @Res() res: Response) {
+    res.setHeader("Cache-Control", "no-store");
+    const agentId = Number(this.config.get("AGENTHUB_AGENT_ID")); // fixed; never trust browser selection
+    const apiKey = this.config.get<string>("AGENTHUB_API_KEY");
+    const baseUrl = this.config.get<string>("AGENTHUB_BACKEND_URL")?.replace(/\\/$/, "");
+    if (!apiKey || !baseUrl || !Number.isSafeInteger(agentId) || agentId <= 0)
+      throw new HttpException("Chat is temporarily unavailable", HttpStatus.SERVICE_UNAVAILABLE);
+    if (body.agentId !== agentId) throw new HttpException("Agent is not configured", HttpStatus.BAD_REQUEST);
+    const userId = req.user?.id ?? req.user?.sub; // set only by trusted auth middleware
+    const payload = { apiKey, agentId, ...(userId != null ? { externalUserId: "my-app:" + userId } : {}) };
+    try {
+      const upstream = await fetch(baseUrl + "/api/agent/api-keys/embedded/me", {
+        method: "POST", headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload), signal: AbortSignal.timeout(15_000),
+      });
+      if (!upstream.ok) throw new HttpException("Chat is temporarily unavailable", HttpStatus.BAD_GATEWAY);
+      res.status(200).type("application/json").send(await upstream.text());
+    } catch (error) {
+      if (error instanceof HttpException) throw error;
+      throw new HttpException("Chat is temporarily unavailable", HttpStatus.SERVICE_UNAVAILABLE);
+    }
+  }
+}
+// Mount behind trusted proxy configuration and rate limiting. Apply the app's
+// authentication/authorization guard instead of @Public() when access is restricted.`,
+        express: `// Express (Node.js 20+). Mount after any optional authentication middleware.
+// Protect this public endpoint with a distributed/IP-aware rate limiter in production.
+// Server environment: AGENTHUB_API_KEY=...; AGENTHUB_AGENT_ID=${agentId}
+${environmentNoteSlash}
+import express from "express";
+
+const router = express.Router();
+router.post("/api/agent-chat/token", async (req, res) => {
+  res.set("Cache-Control", "no-store");
+  const agentId = Number(process.env.AGENTHUB_AGENT_ID); // fixed server-side allowlist
+  const apiKey = process.env.AGENTHUB_API_KEY;
+  const baseUrl = process.env.AGENTHUB_BACKEND_URL?.replace(/\\/$/, "");
+  if (!apiKey || !baseUrl || !Number.isSafeInteger(agentId) || agentId <= 0)
+    return res.status(503).json({ error: "Chat is temporarily unavailable" });
+  if (Number(req.body?.agentId) !== agentId)
+    return res.status(400).json({ error: "Agent is not configured for this application" });
+  const userId = req.user?.id ?? req.user?.sub; // optional identity from trusted middleware
+  try {
+    const upstream = await fetch(baseUrl + "/api/agent/api-keys/embedded/me", {
+      method: "POST", headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ apiKey, agentId, ...(userId != null ? { externalUserId: "my-app:" + userId } : {}) }),
+      signal: AbortSignal.timeout(15_000),
+    });
+    if (!upstream.ok) return res.status(502).json({ error: "Chat is temporarily unavailable" });
+    return res.status(200).type("application/json").send(await upstream.text());
+  } catch {
+    return res.status(503).json({ error: "Chat is temporarily unavailable" });
+  }
+});
+export default router;
+// Ensure express.json() is installed. Never accept API key/backend URL from req.body.`,
+        java: `// Spring Boot 3 / Java 17+. Keep this route public for anonymous embeds,
+// or apply your application's authorization policy. Add a distributed rate limiter.
+// Server environment: AGENTHUB_API_KEY=...; AGENTHUB_AGENT_ID=${agentId}
+${environmentNoteSlash}
+@RestController
+public class AgentEmbedController {
+  private final java.net.http.HttpClient client = java.net.http.HttpClient.newBuilder()
+      .connectTimeout(java.time.Duration.ofSeconds(5)).build();
+  private final com.fasterxml.jackson.databind.ObjectMapper json = new com.fasterxml.jackson.databind.ObjectMapper();
+
+  @Value("\${AGENTHUB_API_KEY}") private String apiKey;
+  @Value("\${AGENTHUB_AGENT_ID}") private int agentId;
+  @Value("\${AGENTHUB_BACKEND_URL}") private String agentHubUrl;
+
+  @PostMapping("/api/agent-chat/token")
+  public ResponseEntity<String> token(@RequestBody Map<String, Object> request,
+                                      org.springframework.security.core.Authentication authentication) throws Exception {
+    if (!Integer.valueOf(agentId).equals(request.get("agentId")))
+      return ResponseEntity.badRequest().cacheControl(CacheControl.noStore()).build();
+    Map<String, Object> payload = new java.util.HashMap<>();
+    payload.put("apiKey", apiKey); payload.put("agentId", agentId);
+    // Omit externalUserId for anonymous access; ignore anonymous security principals.
+    if (authentication != null && authentication.isAuthenticated() &&
+        !(authentication instanceof org.springframework.security.authentication.AnonymousAuthenticationToken))
+      payload.put("externalUserId", "my-app:" + authentication.getName());
+    var upstreamRequest = java.net.http.HttpRequest.newBuilder()
+        .uri(java.net.URI.create(agentHubUrl.replaceAll("/+$", "") + "/api/agent/api-keys/embedded/me"))
+        .timeout(java.time.Duration.ofSeconds(15)).header("Content-Type", "application/json")
+        .POST(java.net.http.HttpRequest.BodyPublishers.ofString(json.writeValueAsString(payload))).build();
+    try {
+      var upstream = client.send(upstreamRequest, java.net.http.HttpResponse.BodyHandlers.ofString());
+      if (upstream.statusCode() != 200)
+        return ResponseEntity.status(502).cacheControl(CacheControl.noStore()).build();
+      return ResponseEntity.ok().cacheControl(CacheControl.noStore())
+          .contentType(MediaType.APPLICATION_JSON).body(upstream.body());
+    } catch (java.io.IOException | InterruptedException error) {
+      if (error instanceof InterruptedException) Thread.currentThread().interrupt();
+      return ResponseEntity.status(503).cacheControl(CacheControl.noStore()).build();
+    }
+  }
+}
+// Imports: org.springframework.beans.factory.annotation.Value, web.bind.annotation.*,
+// org.springframework.http.*, java.util.Map. Do not log the key or token response.`,
+        dotnet: `// ASP.NET Core Minimal API. Configure an IP/user rate-limit policy in production.
+// Authentication can be optional (anonymous demo) or required by your app's policy.
+// Server environment: AGENTHUB_API_KEY=...; AGENTHUB_AGENT_ID=${agentId}
+${environmentNoteSlash}
+using System.Security.Claims;
+using System.Collections.Generic;
+using System.Net.Http.Json;
+
+builder.Services.AddHttpClient("AgentHub", client => client.Timeout = TimeSpan.FromSeconds(15));
+app.MapPost("/api/agent-chat/token", async (AgentTokenRequest body, HttpContext context, IHttpClientFactory clients, IConfiguration config) => {
+    context.Response.Headers.CacheControl = "no-store";
+    if (!int.TryParse(config["AGENTHUB_AGENT_ID"], out var agentId) || agentId <= 0)
+        return Results.StatusCode(503);
+    var apiKey = config["AGENTHUB_API_KEY"];
+    var baseUrl = config["AGENTHUB_BACKEND_URL"]?.TrimEnd('/');
+    if (string.IsNullOrWhiteSpace(apiKey) || string.IsNullOrWhiteSpace(baseUrl))
+        return Results.StatusCode(503);
+    if (body.AgentId != agentId)
+        return Results.BadRequest(new { error = "Agent is not configured for this application" });
+    var subject = context.User.FindFirst(ClaimTypes.NameIdentifier)?.Value;
+    var payload = new Dictionary<string, object?> { ["apiKey"] = apiKey, ["agentId"] = agentId };
+    if (context.User.Identity?.IsAuthenticated == true && !string.IsNullOrEmpty(subject))
+        payload["externalUserId"] = "my-app:" + subject;
+    try {
+        var upstream = await clients.CreateClient("AgentHub").PostAsJsonAsync(
+            baseUrl + "/api/agent/api-keys/embedded/me", payload, context.RequestAborted);
+        if (!upstream.IsSuccessStatusCode) return Results.StatusCode(502);
+        return Results.Text(await upstream.Content.ReadAsStringAsync(context.RequestAborted), "application/json");
+    } catch (HttpRequestException) { return Results.StatusCode(503); }
+}).AllowAnonymous(); // Replace with .RequireAuthorization() for login-only chat.
+public sealed record AgentTokenRequest(int AgentId);
+// Imports: Microsoft.AspNetCore.Http, System.Net.Http.Json, System.Collections.Generic.
+// Add a distributed rate limiter and trusted-proxy configuration for public deployments.`,
+    };
+}

package/dist/components/core/solid-agent/processes/agentHubProcessApi.d.ts

@@ -0,0 +1,15 @@
+export type AgentHubRuntimeProcess = {
+    id: string;
+    agentId: number;
+    status: string;
+    openSessions: number;
+    runningTurns: number;
+    restartNeeded: boolean;
+};
+export declare function listAgentHubProcesses(force?: boolean): Promise<AgentHubRuntimeProcess[]>;
+export declare function stopAgentHubProcess(processId: string): Promise<void>;
+export declare function restartAgentHubProcess(processId: string): Promise<void>;
+export declare function invalidateAgentHubProcessList(): void;
+export declare function stopAgentHubProcessRowAction(event: any): Promise<void>;
+export declare function restartAgentHubProcessRowAction(event: any): Promise<void>;
+//# sourceMappingURL=agentHubProcessApi.d.ts.map

package/dist/components/core/solid-agent/processes/agentHubProcessApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentHubProcessApi.d.ts","sourceRoot":"","sources":["../../../../../src/components/core/solid-agent/processes/agentHubProcessApi.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,sBAAsB,GAAG;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,OAAO,CAAC;CACxB,CAAC;AAgBF,wBAAgB,qBAAqB,CAAC,KAAK,UAAQ,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAWtF;AAED,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,iBAG1D;AAED,wBAAsB,sBAAsB,CAAC,SAAS,EAAE,MAAM,iBAG7D;AAED,wBAAgB,6BAA6B,SAG5C;AAED,wBAAsB,4BAA4B,CAAC,KAAK,EAAE,GAAG,iBAI5D;AAED,wBAAsB,+BAA+B,CAAC,KAAK,EAAE,GAAG,iBAI/D"}

package/dist/components/core/solid-agent/processes/agentHubProcessApi.js

@@ -0,0 +1,122 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+import { solidGet, solidPost } from "../../../../http/solidHttp";
+var inFlight = null;
+var cachedAt = 0;
+var cached = [];
+function unwrap(value) {
+    var current = value;
+    for (var depth = 0; depth < 5 && current; depth += 1) {
+        if (Array.isArray(current))
+            return current;
+        if (Array.isArray(current.data))
+            return current.data;
+        current = current.data;
+    }
+    return [];
+}
+export function listAgentHubProcesses(force) {
+    if (force === void 0) { force = false; }
+    if (!force && Date.now() - cachedAt < 5000)
+        return Promise.resolve(cached);
+    if (inFlight)
+        return inFlight;
+    inFlight = solidGet("/agent-process/manager/processes")
+        .then(function (response) {
+        cached = unwrap(response === null || response === void 0 ? void 0 : response.data);
+        cachedAt = Date.now();
+        return cached;
+    })
+        .finally(function () { inFlight = null; });
+    return inFlight;
+}
+export function stopAgentHubProcess(processId) {
+    return __awaiter(this, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, solidPost("/agent-process/manager/processes/".concat(encodeURIComponent(processId), "/stop"), {})];
+                case 1:
+                    _a.sent();
+                    invalidateAgentHubProcessList();
+                    return [2 /*return*/];
+            }
+        });
+    });
+}
+export function restartAgentHubProcess(processId) {
+    return __awaiter(this, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, solidPost("/agent-process/manager/processes/".concat(encodeURIComponent(processId), "/restart"), {})];
+                case 1:
+                    _a.sent();
+                    invalidateAgentHubProcessList();
+                    return [2 /*return*/];
+            }
+        });
+    });
+}
+export function invalidateAgentHubProcessList() {
+    cachedAt = 0;
+    if (typeof window !== "undefined")
+        window.dispatchEvent(new Event("agent-process-manager-updated"));
+}
+export function stopAgentHubProcessRowAction(event) {
+    var _a;
+    return __awaiter(this, void 0, void 0, function () {
+        var processId;
+        return __generator(this, function (_b) {
+            processId = (_a = event === null || event === void 0 ? void 0 : event.rowData) === null || _a === void 0 ? void 0 : _a.processId;
+            if (!processId)
+                throw new Error("This process has no runtime process ID.");
+            return [2 /*return*/, stopAgentHubProcess(String(processId))];
+        });
+    });
+}
+export function restartAgentHubProcessRowAction(event) {
+    var _a;
+    return __awaiter(this, void 0, void 0, function () {
+        var processId;
+        return __generator(this, function (_b) {
+            processId = (_a = event === null || event === void 0 ? void 0 : event.rowData) === null || _a === void 0 ? void 0 : _a.processId;
+            if (!processId)
+                throw new Error("This process has no runtime process ID.");
+            return [2 /*return*/, restartAgentHubProcess(String(processId))];
+        });
+    });
+}
+//# sourceMappingURL=agentHubProcessApi.js.map

package/dist/components/core/solid-agent/processes/agentHubProcessApi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentHubProcessApi.js","sourceRoot":"","sources":["../../../../../src/components/core/solid-agent/processes/agentHubProcessApi.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAWjE,IAAI,QAAQ,GAA6C,IAAI,CAAC;AAC9D,IAAI,QAAQ,GAAG,CAAC,CAAC;AACjB,IAAI,MAAM,GAA6B,EAAE,CAAC;AAE1C,SAAS,MAAM,CAAC,KAAU;IACxB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,IAAI,OAAO,EAAE,KAAK,IAAI,CAAC,EAAE;QACpD,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;YAAE,OAAO,OAAO,CAAC;QAC3C,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC;YAAE,OAAO,OAAO,CAAC,IAAI,CAAC;QACrD,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;KACxB;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,KAAa;IAAb,sBAAA,EAAA,aAAa;IACjD,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,GAAG,IAAI;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3E,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,QAAQ,GAAG,QAAQ,CAAC,kCAAkC,CAAC;SACpD,IAAI,CAAC,UAAC,QAAa;QAClB,MAAM,GAAG,MAAM,CAAC,QAAQ,aAAR,QAAQ,uBAAR,QAAQ,CAAE,IAAI,CAAC,CAAC;QAChC,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACtB,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;SACD,OAAO,CAAC,cAAQ,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACvC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAgB,mBAAmB,CAAC,SAAiB;;;;wBACzD,qBAAM,SAAS,CAAC,2CAAoC,kBAAkB,CAAC,SAAS,CAAC,UAAO,EAAE,EAAE,CAAC,EAAA;;oBAA7F,SAA6F,CAAC;oBAC9F,6BAA6B,EAAE,CAAC;;;;;CACjC;AAED,MAAM,UAAgB,sBAAsB,CAAC,SAAiB;;;;wBAC5D,qBAAM,SAAS,CAAC,2CAAoC,kBAAkB,CAAC,SAAS,CAAC,aAAU,EAAE,EAAE,CAAC,EAAA;;oBAAhG,SAAgG,CAAC;oBACjG,6BAA6B,EAAE,CAAC;;;;;CACjC;AAED,MAAM,UAAU,6BAA6B;IAC3C,QAAQ,GAAG,CAAC,CAAC;IACb,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,MAAM,CAAC,aAAa,CAAC,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC,CAAC;AACtG,CAAC;AAED,MAAM,UAAgB,4BAA4B,CAAC,KAAU;;;;;YACrD,SAAS,GAAG,MAAA,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,OAAO,0CAAE,SAAS,CAAC;YAC5C,IAAI,CAAC,SAAS;gBAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;YAC3E,sBAAO,mBAAmB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,EAAC;;;CAC/C;AAED,MAAM,UAAgB,+BAA+B,CAAC,KAAU;;;;;YACxD,SAAS,GAAG,MAAA,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,OAAO,0CAAE,SAAS,CAAC;YAC5C,IAAI,CAAC,SAAS;gBAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;YAC3E,sBAAO,sBAAsB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,EAAC;;;CAClD","sourcesContent":["import { solidGet, solidPost } from \"../../../../http/solidHttp\";\n\nexport type AgentHubRuntimeProcess = {\n  id: string;\n  agentId: number;\n  status: string;\n  openSessions: number;\n  runningTurns: number;\n  restartNeeded: boolean;\n};\n\nlet inFlight: Promise<AgentHubRuntimeProcess[]> | null = null;\nlet cachedAt = 0;\nlet cached: AgentHubRuntimeProcess[] = [];\n\nfunction unwrap(value: any): any {\n  let current = value;\n  for (let depth = 0; depth < 5 && current; depth += 1) {\n    if (Array.isArray(current)) return current;\n    if (Array.isArray(current.data)) return current.data;\n    current = current.data;\n  }\n  return [];\n}\n\nexport function listAgentHubProcesses(force = false): Promise<AgentHubRuntimeProcess[]> {\n  if (!force && Date.now() - cachedAt < 5000) return Promise.resolve(cached);\n  if (inFlight) return inFlight;\n  inFlight = solidGet(\"/agent-process/manager/processes\")\n    .then((response: any) => {\n      cached = unwrap(response?.data);\n      cachedAt = Date.now();\n      return cached;\n    })\n    .finally(() => { inFlight = null; });\n  return inFlight;\n}\n\nexport async function stopAgentHubProcess(processId: string) {\n  await solidPost(`/agent-process/manager/processes/${encodeURIComponent(processId)}/stop`, {});\n  invalidateAgentHubProcessList();\n}\n\nexport async function restartAgentHubProcess(processId: string) {\n  await solidPost(`/agent-process/manager/processes/${encodeURIComponent(processId)}/restart`, {});\n  invalidateAgentHubProcessList();\n}\n\nexport function invalidateAgentHubProcessList() {\n  cachedAt = 0;\n  if (typeof window !== \"undefined\") window.dispatchEvent(new Event(\"agent-process-manager-updated\"));\n}\n\nexport async function stopAgentHubProcessRowAction(event: any) {\n  const processId = event?.rowData?.processId;\n  if (!processId) throw new Error(\"This process has no runtime process ID.\");\n  return stopAgentHubProcess(String(processId));\n}\n\nexport async function restartAgentHubProcessRowAction(event: any) {\n  const processId = event?.rowData?.processId;\n  if (!processId) throw new Error(\"This process has no runtime process ID.\");\n  return restartAgentHubProcess(String(processId));\n}\n"]}