feat: ship agent onboarding runtime

packages/env/package.json

@@ -4,6 +4,7 @@
   "private": true,
   "type": "module",
   "exports": {
+    "./agent": "./src/agent.ts",
     "./convex": "./src/convex.ts",
     "./native": "./src/native.ts",
     "./server": "./src/server.ts",

packages/env/src/agent.ts

@@ -0,0 +1,89 @@
+import { createEnv } from "@t3-oss/env-core";
+import { z } from "zod";
+
+/**
+ * Runtime environment for the Flue 2.0 + Hono + AgentOS intelligence
+ * runtime (@code/agents). Validated once at process start.
+ *
+ * Convex remains the durable source of truth; these keys configure only the
+ * runtime process: model routing, persistence, service auth, and the
+ * AgentOS/Rivet host connection.
+ */
+export const env = createEnv({
+  emptyStringAsUndefined: true,
+  runtimeEnv: process.env,
+  server: {
+    AGENT_MODEL_API: z.string().min(1).default("openai-completions"),
+    AGENT_MODEL_API_KEY: z.string().min(1),
+    AGENT_MODEL_BASE_URL: z.url(),
+    AGENT_MODEL_CONTEXT_WINDOW: z.coerce
+      .number()
+      .int()
+      .positive()
+      .default(1_048_576),
+    AGENT_MODEL_MAX_TOKENS: z.coerce.number().int().positive().default(131_072),
+    AGENT_MODEL_NAME: z.string().min(1).default("mimo-v2.5"),
+    // Model routing — Cheaptricks OpenAI-compatible provider.
+    AGENT_MODEL_PROVIDER: z.string().min(1).default("cheaptricks"),
+    // Local workspace root for project VMs and generated artifacts.
+    AGENT_WORKSPACE_ROOT: z.string().min(1),
+    // Convex Site base for service HTTP actions (the .convex.site host).
+    // Runtime → Convex callbacks POST bearer-authenticated calls here.
+    CONVEX_SITE_URL: z.url(),
+    // Convex control plane (the .convex.cloud deployment URL).
+    CONVEX_URL: z.url(),
+    // Flue SQLite canonical conversation state.
+    FLUE_DB_PATH: z.string().min(1).default("/srv/zopu/data/flue/flue.db"),
+    // Service auth between Convex and this runtime.
+    FLUE_DB_TOKEN: z.string().min(1),
+    HOST: z.string().min(1).default("127.0.0.1"),
+    // HTTP listen config.
+    PORT: z.coerce.number().int().positive().default(3000),
+    // AgentOS / Rivet host connection. Accepts a full URL
+    // (http://namespace:token@127.0.0.1:6420) or a bare host:port
+    // (127.0.0.1:6420), normalizing the latter to http://.
+    RIVET_ENDPOINT: z
+      .string()
+      .min(1)
+      .refine(
+        (val) => {
+          try {
+            const candidate = /^https?:\/\//u.test(val) ? val : `http://${val}`;
+            void new URL(candidate);
+            return true;
+          } catch {
+            return false;
+          }
+        },
+        { message: "RIVET_ENDPOINT must be a valid URL or host:port" }
+      )
+      .transform((val) => (/^https?:\/\//u.test(val) ? val : `http://${val}`)),
+    // Distinct endpoint the Rivet Engine invokes to reach this process's
+    // in-process serverless registry handler (mounted by the Hono app at
+    // RIVET_SERVERLESS_BASE_PATH). This is NOT the Engine control-plane URL
+    // (that is RIVET_ENDPOINT); it is how the Engine calls back into the
+    // registry handler co-hosted in this Node process. Defaults to the local
+    // app listener.
+    RIVET_SERVERLESS_ENDPOINT: z
+      .string()
+      .min(1)
+      .refine(
+        (val) => {
+          try {
+            const candidate = /^https?:\/\//u.test(val) ? val : `http://${val}`;
+            void new URL(candidate);
+            return true;
+          } catch {
+            return false;
+          }
+        },
+        {
+          message: "RIVET_SERVERLESS_ENDPOINT must be a valid URL or host:port",
+        }
+      )
+      .transform((val) => (/^https?:\/\//u.test(val) ? val : `http://${val}`))
+      .default("http://127.0.0.1:3000/internal/rivet"),
+    RIVET_WORKSPACE_TOKEN: z.string().min(1),
+  },
+  skipValidation: process.env.SKIP_ENV_VALIDATION === "true",
+});

packages/env/src/convex.ts

@@ -5,7 +5,10 @@ export const env = createEnv({
   emptyStringAsUndefined: true,
   runtimeEnv: process.env,
   server: {
+    AGENT_BACKEND_URL: z.url().optional(),
     CONVEX_SITE_URL: z.url().optional(),
+    FLUE_DB_TOKEN: z.string().min(1).optional(),
+    FLUE_URL: z.url().optional(),
     GITEA_TOKEN: z.string().min(1).optional(),
     GITEA_URL: z.url().default("https://git.openputer.com"),
     GITEA_WEBHOOK_SECRET: z.string().min(1).optional(),