@humwick/server 0.130.3 → 0.130.4

package/src/db/workflow-execution.ts

@@ -1,8 +1,8 @@
-// Task ownership and coordinator routing see the same execution facts for runs and item lanes.
+// Task ownership, coordinator routing and spawn admission share execution facts for runs and item lanes.
 export const WORKFLOW_EXECUTIONS_SQL = `(
-  SELECT scope, id, taskId, coordinator, status, reason, awaiting FROM kernel_entity__workflow__run
+  SELECT scope, id, taskId, coordinator, callerAgentId, status, reason, awaiting FROM kernel_entity__workflow__run
   UNION ALL
-  SELECT item.scope, item.id, owner.taskId, owner.coordinator,
+  SELECT item.scope, item.id, owner.taskId, owner.coordinator, owner.callerAgentId,
     json_extract(item.lane, '$.status') AS status, json_extract(item.lane, '$.reason') AS reason, json_extract(item.lane, '$.awaiting') AS awaiting
   FROM kernel_entity__workflow__activation item
   JOIN kernel_entity__workflow__run owner ON owner.scope = item.scope AND owner.id = item.runId

package/src/dev.ts

@@ -2,7 +2,7 @@ import { writeChildEnv } from "@humwick/sdk/env";
 import { instanceDirectoryEnv } from "@humwick/sdk/isolated-env";
 import { execFile } from "node:child_process";
 import { shellQuote } from "@humwick/sdk/shell-utils";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { homedir, hostname as osHostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
@@ -10,6 +10,7 @@ import { promisify } from "node:util";
 import { packPackage, privateWorkspaceDependencies, workspaceDependencyClosure } from "./package-pack";
 import { generateToken, renderEnvFile } from "./setup";
 import { createDaemonPlan, executeDaemonPlan, MANAGED_MARKER } from "./daemon";
+import { npmInstallIntoPrefix } from "./runtime-install";
 
 const execFileAsync = promisify(execFile);
 const DEV_MARKER = "agent-relay-dev-profile";
@@ -149,13 +150,10 @@ export function createDevInstallPlan(options: {
 export async function executeDevInstallPlan(plan: DevInstallPlan, options: { dryRun?: boolean } = {}): Promise<DevInstallResult> {
   if (options.dryRun) return { plan, tarballs: [], output: formatDevInstallPlan(plan) };
   const packed = await executeDevPackPlan(plan.packPlan);
-  await mkdir(plan.prefix, { recursive: true });
-  ensureDevPrefixPackageJson(plan.prefix);
-  const command = ["install", "--prefix", plan.prefix, "--no-audit", "--no-fund", "--force", ...packed.tarballs];
-  const result = await execFileAsync("npm", command, { cwd: plan.prefix });
+  const installed = await npmInstallIntoPrefix(plan.prefix, packed.tarballs);
   const output = [
     packed.output,
-    result.stdout.trim(),
+    installed,
     `Installed into ${plan.prefix}`,
   ].filter(Boolean).join("\n");
   return { plan, tarballs: packed.tarballs, output };
@@ -426,13 +424,6 @@ function devEnvFile(rootDir = defaultDevRoot()): string {
   return join(rootDir, "env");
 }
 
-function ensureDevPrefixPackageJson(prefix: string): void {
-  mkdirSync(prefix, { recursive: true });
-  const path = join(prefix, "package.json");
-  if (existsSync(path)) return;
-  writeFileSync(path, JSON.stringify({ private: true, name: "agent-relay-dev-install" }, null, 2) + "\n", "utf8");
-}
-
 function devServiceCommands(action: DevServiceAction, options: {
   serverUnit: string;
   orchestratorUnit: string;

package/src/init.ts

@@ -0,0 +1,299 @@
+// `humwick init` (#2680): one resumable install of a persistent server. It composes the existing
+// primitives (setup env file, runtime install, daemon planner) and ends with a one-time dashboard
+// login link, so nobody copies the admin token. Every failure names its step and a repair command.
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { connect } from "node:net";
+import { homedir, hostname, userInfo } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { RELAY_TOKEN_HEADER, errMessage } from "@humwick/sdk";
+import { VERSION } from "./config";
+import { createDaemonPlan, detectDaemonEnvironment, executeDaemonPlan } from "./daemon";
+import { installChannelsHostService } from "./channels-host-service";
+import { executeSetupPlan, resolveSetupPlan, setupPlanToken } from "./setup";
+import { runtimeBinPath, runtimeTarballDir } from "./runtime-prefix";
+import { isServerTarball, npmInstallIntoPrefix } from "./runtime-install";
+import { sanitizeOrchestratorId } from "./utils";
+
+const execFileAsync = promisify(execFile);
+const SERVER_PACKAGE = "@humwick/server";
+const ORCHESTRATOR_UNIT = "agent-relay-orchestrator.service";
+
+export type InitStep = "preflight" | "setup" | "runtime" | "service" | "health" | "host" | "login";
+
+export class InitStepError extends Error {
+  constructor(readonly step: InitStep, message: string, readonly repair: string) { super(message); }
+}
+
+export type InitOptions = {
+  tarballDir?: string;
+  runtimePrefix?: string;
+  envFile?: string;
+  host?: string;
+  port?: number;
+  dbPath?: string;
+  healthTimeoutMs?: number;
+};
+
+export type InitResult = {
+  ok: true;
+  version: string;
+  dashboardUrl: string;
+  loginUrl: string;
+  loginExpiresAt?: string;
+  service: { unit: string; kind: string; scope: string; file?: string };
+  envFile: string;
+  dbPath: string;
+  runtimePrefix: string;
+  runtime: { source: "registry" | "tarballs"; installed: boolean };
+  linger: "yes" | "no" | "unknown";
+  resumed: boolean;
+  /** This machine, joined as the server's first orchestrator host. */
+  host: { id: string; unit: string; joined: boolean };
+  warnings: string[];
+  next: string[];
+};
+
+type Log = (line: string) => void;
+
+async function run(command: string[], timeoutMs = 15_000): Promise<{ ok: boolean; out: string }> {
+  try {
+    const { stdout, stderr } = await execFileAsync(command[0]!, command.slice(1), { timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 });
+    return { ok: true, out: `${stdout}${stderr}`.trim() };
+  } catch (e) {
+    const err = e as { stdout?: string; stderr?: string; message: string };
+    return { ok: false, out: `${err.stdout ?? ""}${err.stderr ?? ""}`.trim() || err.message };
+  }
+}
+
+function probeHost(host: string): string {
+  return host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
+}
+
+/** True when something accepts TCP connections on host:port. */
+export function portInUse(host: string, port: number, timeoutMs = 2_000): Promise<boolean> {
+  return new Promise((done) => {
+    const socket = connect({ host: probeHost(host), port });
+    const finish = (inUse: boolean) => { socket.destroy(); done(inUse); };
+    socket.setTimeout(timeoutMs, () => finish(false));
+    socket.once("connect", () => finish(true));
+    socket.once("error", () => finish(false));
+  });
+}
+
+async function healthy(baseUrl: string): Promise<boolean> {
+  try {
+    return (await fetch(`${baseUrl}/api/health`, { signal: AbortSignal.timeout(5_000) })).ok;
+  } catch {
+    return false;
+  }
+}
+
+async function unitActive(unit: string): Promise<boolean> {
+  return (await run(["systemctl", "--user", "is-active", unit])).out === "active";
+}
+
+async function preflight(port: number, host: string, unit: string, log: Log): Promise<{ linger: InitResult["linger"]; resumed: boolean }> {
+  if (process.platform === "win32") throw new InitStepError("preflight", "native Windows is not supported", "Install WSL2 (wsl --install), then run init inside the Linux distribution.");
+  if (process.platform !== "linux") throw new InitStepError("preflight", `init installs a systemd user service; ${process.platform} is not supported yet`, "Run the server in the foreground: humwick");
+  const bun = Bun.which("bun");
+  if (!bun) throw new InitStepError("preflight", "bun is not on PATH", "curl -fsSL https://bun.sh/install | bash, then open a new shell");
+  if (!Bun.which("npm")) throw new InitStepError("preflight", "npm is not on PATH (the runtime installs with npm)", "Install Node.js 20 or newer with npm, e.g. sudo apt install nodejs npm");
+  const node = await run(["node", "--version"]);
+  const nodeMajor = Number(/^v(\d+)/.exec(node.out)?.[1] ?? 0);
+  if (!node.ok || nodeMajor < 20) throw new InitStepError("preflight", `Node.js 20 or newer is required (found ${node.ok ? node.out : "none"})`, "Install Node.js 20 or newer with npm");
+  const manager = await run(["systemctl", "--user", "show-environment"]);
+  if (!manager.ok) throw new InitStepError("preflight", `no systemd user manager is reachable: ${manager.out.split("\n")[0]}`, `Log in through a real session (ssh or console), or run: sudo loginctl enable-linger ${userInfo().username}`);
+  const lingerOut = await run(["loginctl", "show-user", userInfo().username, "--property=Linger", "--value"]);
+  const linger = lingerOut.ok ? (lingerOut.out === "yes" ? "yes" : "no") : "unknown";
+  const resumed = await unitActive(unit);
+  if (!resumed && await portInUse(host, port)) {
+    const other = await healthy(`http://${probeHost(host)}:${port}`) ? "a Humwick server that init does not manage (a foreground trial?)" : "another program";
+    throw new InitStepError("preflight", `port ${port} is in use by ${other}`, `Stop it, or pass --port <free port>. To keep a trial server's data, pass --db-path <its agent-relay.db>.`);
+  }
+  log(`preflight: bun ${Bun.version}, node ${node.out}, systemd user manager, linger ${linger}, port ${port} ${resumed ? "held by this install" : "free"}`);
+  return { linger, resumed };
+}
+
+function fileDigest(path: string): string {
+  return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+
+/** Copy the tarballs into the runtime's tarball dir; false when the runtime already has these exact files. */
+function stageTarballs(sourceDir: string, prefix: string): { tarballs: string[]; changed: boolean } {
+  const names = readdirSync(sourceDir).filter((name) => name.endsWith(".tgz")).sort();
+  if (!names.some(isServerTarball)) throw new InitStepError("runtime", `no humwick-server-*.tgz in ${sourceDir}`, "Pack the packages: humwick dev pack --packages sdk,server,runner,orchestrator");
+  const target = runtimeTarballDir(prefix);
+  const existing = existsSync(target) ? readdirSync(target).filter((name) => name.endsWith(".tgz")).sort() : [];
+  const same = existing.join("\n") === names.join("\n")
+    && names.every((name) => fileDigest(join(sourceDir, name)) === fileDigest(join(target, name)));
+  if (!same) {
+    mkdirSync(target, { recursive: true });
+    for (const name of existing) rmSync(join(target, name), { force: true });
+    for (const name of names) copyFileSync(join(sourceDir, name), join(target, name));
+  }
+  return { tarballs: names.map((name) => join(target, name)), changed: !same };
+}
+
+function installedServerVersion(prefix: string): string | undefined {
+  try {
+    return (JSON.parse(readFileSync(join(prefix, "node_modules", SERVER_PACKAGE, "package.json"), "utf8")) as { version?: string }).version;
+  } catch {
+    return undefined;
+  }
+}
+
+async function installRuntime(prefix: string, tarballDir: string | undefined, log: Log): Promise<boolean> {
+  const binPresent = existsSync(runtimeBinPath("agent-relay", prefix));
+  const staged = tarballDir ? stageTarballs(resolve(tarballDir), prefix) : undefined;
+  const upToDate = binPresent && installedServerVersion(prefix) === VERSION && (staged ? !staged.changed : true);
+  if (upToDate) {
+    log(`runtime: ${SERVER_PACKAGE}@${VERSION} already installed in ${prefix}`);
+    return false;
+  }
+  const specs = staged ? staged.tarballs : [`${SERVER_PACKAGE}@${VERSION}`];
+  try {
+    await npmInstallIntoPrefix(prefix, specs);
+  } catch (e) {
+    throw new InitStepError("runtime", errMessage(e), `Check network access to the npm registry, then rerun: humwick init${tarballDir ? ` --tarball-dir ${tarballDir}` : ""}`);
+  }
+  if (!existsSync(runtimeBinPath("agent-relay", prefix))) throw new InitStepError("runtime", `the install finished but ${runtimeBinPath("agent-relay", prefix)} is missing`, "Rerun init; if it repeats, remove the runtime prefix and rerun");
+  log(`runtime: installed ${staged ? `${staged.tarballs.length} packed tarballs` : `${SERVER_PACKAGE}@${VERSION}`} into ${prefix}`);
+  return true;
+}
+
+async function waitHealthy(baseUrl: string, timeoutMs: number, unit: string): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await healthy(baseUrl) && await unitActive(unit)) return;
+    await Bun.sleep(1_000);
+  }
+  throw new InitStepError("health", `${unit} is not healthy at ${baseUrl}/api/health after ${Math.round(timeoutMs / 1000)} s`, `journalctl --user -u ${unit} -n 50 --no-pager`);
+}
+
+/** A call to the local server with the admin token from the env file; it never leaves this machine. */
+async function adminRequest(step: InitStep, baseUrl: string, token: string, method: string, path: string, body?: unknown): Promise<Response> {
+  try {
+    return await fetch(`${baseUrl}${path}`, {
+      method,
+      headers: { [RELAY_TOKEN_HEADER]: token, "content-type": "application/json" },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      signal: AbortSignal.timeout(15_000),
+    });
+  } catch (e) {
+    throw new InitStepError(step, `could not reach ${baseUrl}: ${errMessage(e)}`, "Rerun init; it resumes where it stopped.");
+  }
+}
+
+/**
+ * Join this machine as an orchestrator host (#2680 v1 bar): a host-scoped, single-use bootstrap
+ * token from the local server, then the runtime's own `orchestrator install`. Gate slots and the
+ * agent cap default to sizes derived from the host's CPUs and RAM.
+ */
+async function joinLocalHost(baseUrl: string, token: string, prefix: string, fromTarballs: boolean, log: Log): Promise<InitResult["host"]> {
+  const id = sanitizeOrchestratorId(hostname());
+  const repair = "Rerun init, or in the dashboard open Orchestrators → Add";
+  const joined = !(await unitActive(ORCHESTRATOR_UNIT));
+  if (joined) {
+    const baseDir = join(homedir(), "projects");
+    const minted = await adminRequest("host", baseUrl, token, "POST", "/api/orchestrators/bootstrap", { id, baseDir, relayUrl: baseUrl });
+    if (minted.status !== 201) throw new InitStepError("host", `host bootstrap returned ${minted.status}: ${(await minted.text()).slice(0, 200)}`, repair);
+    const { bootstrapToken } = await minted.json() as { bootstrapToken: string };
+    const install = await run([runtimeBinPath("humwick", prefix), "orchestrator", "install", "--relay-url", baseUrl, "--bootstrap-token", bootstrapToken,
+      "--id", id, "--base-dir", baseDir, "--runtime-prefix", prefix, "--yes", ...(fromTarballs ? ["--skip-install"] : ["--version", VERSION])], 10 * 60_000);
+    if (!install.ok) throw new InitStepError("host", `orchestrator install failed:\n${install.out.split("\n").slice(-20).join("\n")}`, repair);
+  }
+  const deadline = Date.now() + 120_000;
+  for (;;) {
+    const list = await (await adminRequest("host", baseUrl, token, "GET", "/api/orchestrators")).json().catch(() => []) as Array<{ id: string; status?: string }>;
+    if (list.some((h) => h.id === id && h.status === "online")) break;
+    if (Date.now() > deadline) throw new InitStepError("host", `host ${id} did not come online within 120 s`, `journalctl --user -u ${ORCHESTRATOR_UNIT} -n 50 --no-pager`);
+    await Bun.sleep(1_000);
+  }
+  log(`host: ${id} ${joined ? "joined" : "already joined"} and online`);
+  return { id, unit: ORCHESTRATOR_UNIT, joined };
+}
+
+async function mintLoginLink(baseUrl: string, token: string): Promise<{ url: string; expiresAt?: string }> {
+  const response = await adminRequest("login", baseUrl, token, "POST", "/api/auth/login-links", {});
+  if (response.status !== 201) throw new InitStepError("login", `login link request returned ${response.status}: ${(await response.text()).slice(0, 200)}`, "Rerun init to get a fresh login link");
+  const body = await response.json() as { path: string; expiresAt?: number };
+  return { url: `${baseUrl}${body.path}`, ...(body.expiresAt ? { expiresAt: new Date(body.expiresAt * 1000).toISOString() } : {}) };
+}
+
+/** Install or repair a persistent server for this user and return how to open its dashboard. */
+export async function runInit(options: InitOptions = {}, log: Log = () => {}): Promise<InitResult> {
+  const plan = await resolveSetupPlan({
+    ...(options.envFile ? { envFile: options.envFile } : {}),
+    ...(options.host ? { host: options.host } : {}),
+    ...(options.port !== undefined ? { port: options.port } : {}),
+    ...(options.dbPath ? { dbPath: options.dbPath } : {}),
+    ...(options.runtimePrefix ? { runtimePrefix: options.runtimePrefix } : {}),
+  });
+  const port = Number(plan.values.PORT);
+  const host = plan.values.HOST!;
+  const daemonEnv = await detectDaemonEnvironment();
+  const bunDir = dirname(Bun.which("bun") ?? process.execPath);
+  const daemon = createDaemonPlan({ action: "install", envFile: plan.envFile, runtimePrefix: plan.runtimePrefix, port, host, pathPrefix: [bunDir], enable: true, start: true }, daemonEnv);
+  const unit = `${daemon.name}.service`;
+
+  const { linger, resumed } = await preflight(port, host, unit, log);
+
+  try {
+    await executeSetupPlan(plan);
+  } catch (e) {
+    throw new InitStepError("setup", errMessage(e), `Move the file aside, or rerun with an explicit --env-file`);
+  }
+  log(`setup: ${plan.reused ? "kept" : "wrote"} ${plan.envFile} (admin token ${plan.reused ? "unchanged" : "generated"})`);
+
+  const installed = await installRuntime(plan.runtimePrefix, options.tarballDir, log);
+
+  const previousUnit = daemon.file && existsSync(daemon.file.path) ? readFileSync(daemon.file.path, "utf8") : undefined;
+  const restart = resumed && (installed || previousUnit !== daemon.file?.content);
+  try {
+    await executeDaemonPlan(daemon);
+    if (restart) {
+      const restarted = await run(["systemctl", "--user", "restart", unit], 60_000);
+      if (!restarted.ok) throw new Error(restarted.out);
+    }
+    // The server supervises a channels-host service; `daemon install` sets it up the same way.
+    log(await installChannelsHostService({ ownerServiceName: daemon.name, runtimePrefix: plan.runtimePrefix, legacyEnvFile: plan.envFile, start: true, env: daemonEnv, onlyIfConfigured: false }));
+  } catch (e) {
+    throw new InitStepError("service", errMessage(e), `systemctl --user status ${unit} agent-relay-channels-host.service`);
+  }
+  log(`service: ${unit} enabled and ${restart ? "restarted" : resumed ? "running" : "started"}`);
+
+  const baseUrl = `http://${probeHost(host)}:${port}`;
+  await waitHealthy(baseUrl, options.healthTimeoutMs ?? 60_000, unit);
+  log(`health: ${baseUrl}/api/health ok`);
+
+  const token = setupPlanToken(plan);
+  if (!token) throw new InitStepError("setup", `${plan.envFile} has no admin token; init needs it to join this host and mint the login link`, `humwick init --env-file <a new path>, or add a token to ${plan.envFile}`);
+  const localHost = await joinLocalHost(baseUrl, token, plan.runtimePrefix, Boolean(options.tarballDir), log);
+  const login = await mintLoginLink(baseUrl, token);
+  const warnings = [...plan.warnings, ...daemon.warnings.filter((w) => !w.startsWith("Runtime binary is not installed"))];
+  if (linger !== "yes") warnings.push(`Linger is ${linger}: the service stops when you log out. Keep it running with: sudo loginctl enable-linger ${userInfo().username}`);
+  return {
+    ok: true,
+    version: VERSION,
+    dashboardUrl: `${baseUrl}/`,
+    loginUrl: login.url,
+    ...(login.expiresAt ? { loginExpiresAt: login.expiresAt } : {}),
+    service: { unit, kind: daemon.kind, scope: daemon.scope, ...(daemon.serviceFilePath ? { file: daemon.serviceFilePath } : {}) },
+    envFile: plan.envFile,
+    dbPath: plan.values.DB_PATH!,
+    runtimePrefix: plan.runtimePrefix,
+    runtime: { source: options.tarballDir ? "tarballs" : "registry", installed },
+    linger,
+    resumed,
+    host: localHost,
+    warnings,
+    next: [
+      `Open the login link (one use, 15 minutes) on this machine, or from yours through: ssh -L ${port}:127.0.0.1:${port} ${userInfo().username}@<this-host>`,
+      `This machine runs agents as host ${localHost.id}. Set up a provider in the dashboard, then spawn your first agent. More machines: Orchestrators → Add.`,
+      "Lost the link? Rerun init: it repairs the install and prints a fresh one, without changing the admin token.",
+    ],
+  };
+}

package/src/invite-link.ts

@@ -1,11 +1,18 @@
-// #3567 D2 — the invite link `/invite/<code>` the API hands out opens the dashboard's accept screen.
-// The code moves into the URL fragment, which browsers never send to a server or in a Referer.
-const INVITE_PATH = /^\/invite\/([A-Za-z0-9_-]{16,128})$/;
+// #3567 D2 — the invite link `/invite/<code>` opens the dashboard's accept screen; #2680 — the login
+// link `/login/<code>` that `humwick init` prints opens the dashboard signed in. The code moves into
+// the URL fragment, which browsers never send to a server or in a Referer.
+const LINK_PATHS: Array<[RegExp, string]> = [
+  [/^\/invite\/([A-Za-z0-9_-]{16,128})$/, "invite"],
+  // A login code is a signed token (base64url segments joined by dots).
+  [/^\/login\/([A-Za-z0-9_.-]{16,2048})$/, "login"],
+];
 
-/** A redirect to the dashboard accept screen for an invite link, else null. */
-export function inviteLinkRedirect(pathname: string): Response | null {
-  const code = INVITE_PATH.exec(pathname)?.[1];
-  if (!code) return null;
-  // Relative, so a dashboard served under a reverse-proxy prefix keeps its prefix.
-  return new Response(null, { status: 302, headers: { Location: `../#invite=${code}`, "Cache-Control": "no-store", "Referrer-Policy": "no-referrer" } });
+/** A redirect to the dashboard screen for an invite or login link, else null. */
+export function dashboardLinkRedirect(pathname: string): Response | null {
+  for (const [pattern, kind] of LINK_PATHS) {
+    const code = pattern.exec(pathname)?.[1];
+    // Relative, so a dashboard served under a reverse-proxy prefix keeps its prefix.
+    if (code) return new Response(null, { status: 302, headers: { Location: `../#${kind}=${code}`, "Cache-Control": "no-store", "Referrer-Policy": "no-referrer" } });
+  }
+  return null;
 }

package/src/routes/auth.ts

@@ -3,8 +3,8 @@ import { authorityDenied, recordUserManagement } from "../authority-audit";
 // (src/index.ts) so they are reachable unauthenticated — each handler owns its own auth: login
 // verifies credentials, refresh validates the refresh token, logout revokes the presented session.
 // Everything else on the relay still flows through the existing component-token gate.
-import { isRecord, type User } from "@humwick/sdk";
-import { error, json, parseBody, type Handler } from "./_shared";
+import { DEFAULT_USER_ID, isRecord, type User } from "@humwick/sdk";
+import { error, isAdminRequest, json, parseBody, requestUserId, type Handler } from "./_shared";
 import { getAuthProvider, listAuthProviders, mintUserSession, type MintedSession } from "../auth";
 import { getAuthIdentity, getUser, InviteUnavailableError, ValidationError } from "../db";
 import { revokeTokenAsync } from "../token-db-write.ts";
@@ -14,6 +14,7 @@ import { readSessionCookie, sessionOriginAllowed, withSessionCookie } from "../a
 import { getComponentAuth } from "../security";
 import { acceptInvite, userInvitesEnabled } from "../services/user-onboarding";
 import { invitesDisabled } from "./users";
+import { mintLoginLink, redeemLoginLink } from "../auth/login-link";
 
 /** Public projection of a user for login/refresh responses — never leaks internal-only columns. */
 function userView(user: User): Record<string, unknown> {
@@ -120,3 +121,30 @@ export const postAcceptInviteRoute: Handler = async (req) => {
     throw e;
   }
 };
+
+/**
+ * POST /api/auth/login-links — admin only (#2680). Body `{ userId? }`, default the seeded admin user.
+ * `humwick init` calls this with the admin token so the first login needs no token at all.
+ */
+export const postLoginLinkRoute: Handler = async (req) => {
+  if (!isAdminRequest(req)) return (await authorityDenied(req, "only an admin can mint a login link"));
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const userId = isRecord(parsed.body) && typeof parsed.body.userId === "string" ? parsed.body.userId : DEFAULT_USER_ID;
+  const user = getUser(userId);
+  if (!user || user.status !== "active") return error("user not found or not active", 404);
+  const link = await mintLoginLink(user, `auth:login-link:${requestUserId(req)}`);
+  recordUserManagement(req, user.id, "mint login link");
+  return json(link, 201);
+};
+
+/** POST /api/auth/login-links/redeem — public; the single-use link code is the credential. */
+export const postRedeemLoginLinkRoute: Handler = async (req) => {
+  if (!sessionOriginAllowed(req, false)) return (await authorityDenied(req, "origin not allowed", 403));
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const code = isRecord(parsed.body) ? parsed.body.code : undefined;
+  const user = typeof code === "string" && code ? await redeemLoginLink(code) : null;
+  if (!user) return (await authorityDenied(req, "login link is invalid, expired or already used", 401));
+  return sessionResponse(req, user, (await mintUserSession(user)));
+};

package/src/routes/host-providers.ts

@@ -8,6 +8,9 @@ import { error, json, parseBody, type Handler } from "./_shared";
 import { getHostProviderSetting } from "../host-provider-store";
 import { isHostSwitchableProvider, isOptInProvider, type HostProviderEnablementSetting } from "../host-provider-enablement";
 import { setHostProviderEnabled, setHostProvidersBulk } from "../services/host-providers";
+import { connectProviderApiKey } from "../services/provider-api-key";
+import { VaultError } from "../secrets-vault/keys";
+import { vaultActorOf } from "../services/auth-context";
 import type { SpawnProvider } from "@humwick/sdk";
 
 function hostProviderView(hostId: string, advertised: SpawnProvider[], setting: HostProviderEnablementSetting | null, catalogProviders: SpawnProvider[]) {
@@ -71,3 +74,18 @@ export const putHostProvidersBulkRoute: Handler = async (req, params) => {
     throw e;
   }
 };
+
+/** T7689 — first-run provider setup: the operator's key, bound on this host, with a credit window. */
+export const postHostProviderApiKeyRoute: Handler = async (req, params) => {
+  const hostId = cleanString(params.id, "host id", { required: true, max: 120 })!;
+  const provider = cleanString(params.provider, "provider", { required: true, max: 80 })!;
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    return json(await connectProviderApiKey(vaultActorOf(req), hostId, provider, parsed.body, req));
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    if (e instanceof VaultError) return error(e.message, 503);
+    throw e;
+  }
+};

package/src/routes/index.ts

@@ -44,11 +44,11 @@ import { deleteInboxDraftRoute, getChatHistoryImportsRoute, getInboxStateRoute,
 import { postAgentAreaEntered } from "./memory";
 import { deleteMessageById, getCursorRoute, getMessageById, getMessageDeliveryRoute, getMessageStatusRoute, getMessageThread, getMessages, getQueuedMessagesRoute, patchMessage, postClaimMessage, postMessage, postMessageDeliveryAction, postMessageDeliveryAttempt, postMessageReaction, postRenewMessageClaim, postSystemBroadcast } from "./messages";
 import { deleteOrchestratorById, getOrchestratorById, getOrchestrators, patchOrchestratorAgents, postOrchestrator, postOrchestratorAction, postOrchestratorHeartbeat } from "./orchestrator";
-import { getHostProvidersRoute, putHostProviderRoute, putHostProvidersBulkRoute } from "./host-providers";
+import { getHostProvidersRoute, postHostProviderApiKeyRoute, putHostProviderRoute, putHostProvidersBulkRoute } from "./host-providers";
 import { deleteSpawnPolicyRoute, getSpawnPoliciesHealth, getSpawnPoliciesRoute, getSpawnPolicyDiagnostics, getSpawnPolicyHealth, getSpawnPolicyRoute, getSpawnPolicyStatus, postSpawnPolicyRestart, postSpawnPolicyStart, postSpawnPolicyStop, putSpawnPolicyRoute } from "./spawn-policy";
 import { deleteTokenProfileRoute, getTokenById, getTokenMe, getTokenProfiles, getTokens, patchTokenProfile, postIntegrationRuntimeToken, postInteractiveRunnerRuntimeToken, postMcpRuntimeToken, postOrchestratorRunnerToken, postRuntimeTokenRemint, postRuntimeTokenRenew, postToken, postTokenProfile, postTokenRevoke } from "./tokens";
 import { deleteWorkspaceById, getWorkspaceById, getWorkspaceDiagnostics, getWorkspaceDiff, getWorkspaceGitState, getWorkspaceMergePreview, getWorkspaceOrphans, getWorkspaceRecoveryBranches, getWorkspaceStewards, getWorkspaces, postWorkspaceAction, postWorkspaceCleanupStale, postWorkspaceOrphanReclaim, postWorkspaceRecoveryBranchDiscard } from "./workspaces";
-import { getAuthProvidersRoute, postAcceptInviteRoute, postAuthLoginRoute, postAuthLogoutRoute, postAuthRefreshRoute } from "./auth";
+import { getAuthProvidersRoute, postAcceptInviteRoute, postAuthLoginRoute, postAuthLogoutRoute, postAuthRefreshRoute, postLoginLinkRoute, postRedeemLoginLinkRoute } from "./auth";
 import { getActivityEvents, postActivityEvent } from "./activity";
 import { getAnalyticsRoute, getDeliveryQualityRoute, getHealthRoute, getHubMetricsRoute, getLeadTimeRoute, getMaintenanceJobs, getMaintenancePauses, getMaintenanceRunning, getStatsRoute, postMaintenanceJobCancel, postMaintenanceJobPause, postMaintenanceJobResume, postMaintenanceJobRun, postSystemReap } from "./stats";
 import { getApiDocs, getApiSpec } from "./spec";
@@ -103,6 +103,8 @@ const routes: Route[] = [
   route("POST", "/api/auth/refresh", postAuthRefreshRoute),
   route("POST", "/api/auth/logout", postAuthLogoutRoute),
   route("POST", "/api/auth/invites/accept", postAcceptInviteRoute),
+  route("POST", "/api/auth/login-links", postLoginLinkRoute),
+  route("POST", "/api/auth/login-links/redeem", postRedeemLoginLinkRoute),
   route("POST", "/api/users/invites", postUserInvite),
   route("PUT", "/api/users/me/password", putMyPassword),
 
@@ -228,6 +230,7 @@ const routes: Route[] = [
   route("GET", "/api/orchestrators/:id/host-providers", getHostProvidersRoute),
   route("PUT", "/api/orchestrators/:id/host-providers", putHostProvidersBulkRoute),
   route("PUT", "/api/orchestrators/:id/host-providers/:provider", putHostProviderRoute),
+  route("POST", "/api/orchestrators/:id/host-providers/:provider/api-key", postHostProviderApiKeyRoute),
   route("GET", "/api/orchestrators/:id/sessions", getOrchestratorSessions),
   route("GET", "/api/orchestrators/:id/version", getOrchestratorVersion),
   route("GET", "/api/orchestrators/:id/logs/:session", getOrchestratorLogs),

package/src/routes/orchestrator-bootstrap.ts

@@ -61,6 +61,8 @@ export const postOrchestratorBootstrap: Handler = async (req) => {
       version,
       pathPrefix: pathPrefix ?? [],
       token: bootstrapToken.record,
+      // The single-use credential itself, for a caller that runs `orchestrator install` without the shell command (`humwick init`, #2680).
+      bootstrapToken: bootstrapToken.token,
       expiresAt: bootstrapToken.record.expiresAt,
     }, 201);
   } catch (e) {

package/src/routes/secrets-backup.ts

@@ -2,7 +2,7 @@ import { isRecord } from "@humwick/sdk";
 import { ValidationError } from "../db/connection";
 import { readBodyBytes } from "../http-body";
 import { getComponentAuth } from "../security";
-import { authContextFromRequest } from "../services/auth-context";
+import { vaultActorOf } from "../services/auth-context";
 import { exportVaultBackup, vaultBackupStatus, writeVaultBackup } from "../secrets-vault/backup";
 import { VaultError } from "../secrets-vault/keys";
 import { restoreVaultBackup } from "../secrets-vault/restore";
@@ -30,8 +30,7 @@ function operatorRoute(handle: (body: Record<string, unknown>, actor: string) =>
       try { body = read.bytes.byteLength ? JSON.parse(new TextDecoder().decode(read.bytes)) : {}; } catch { return error("invalid JSON body", 400); }
     }
     if (!isRecord(body)) return error("body must be an object", 400);
-    const ctx = authContextFromRequest(req);
-    try { return await handle(body, ctx.actor.kind === "system" ? "operator" : ctx.actor.id); }
+    try { return await handle(body, vaultActorOf(req)); }
     catch (cause) { return backupError(cause); }
   };
 }

package/src/routes/secrets-import.ts

@@ -1,7 +1,7 @@
 import { ValidationError } from "../db/connection";
 import { isRecord } from "@humwick/sdk";
 import { getComponentAuth } from "../security";
-import { authContextFromRequest } from "../services/auth-context";
+import { vaultActorOf } from "../services/auth-context";
 import { importVaultSecrets, previewVaultImport } from "../secrets-vault/import";
 import { VaultError } from "../secrets-vault/keys";
 import { SecretsBrokerError } from "../secrets-broker/error";
@@ -16,9 +16,8 @@ function importRoute(preview: boolean): Handler {
     const parsed = await parseBody<unknown>(req);
     if (!parsed.ok) return error(parsed.error, parsed.status);
     if (!isRecord(parsed.body)) return error("import must be an object", 400);
-    const ctx = authContextFromRequest(req);
     try {
-      return json(preview ? await previewVaultImport(parsed.body.source) : await importVaultSecrets(ctx.actor.kind === "system" ? "operator" : ctx.actor.id, parsed.body), preview ? 200 : 201);
+      return json(preview ? await previewVaultImport(parsed.body.source) : await importVaultSecrets(vaultActorOf(req), parsed.body), preview ? 200 : 201);
     } catch (cause) {
       if (cause instanceof ValidationError) return error(cause.message, 400);
       if (cause instanceof VaultError) return error(cause.message, cause.code === "exists" ? 409 : cause.code === "not_found" ? 404 : 503);

package/src/routes/secrets-vault.ts

@@ -2,7 +2,7 @@ import { listSecretAuditAsync } from "../db/secrets-broker-async";
 import { parseSecretName, scopedSecretName, secretEnvironment } from "../secrets-vault/scope";
 import { builtinVault, backendCall, readVaultLastResolved } from "../secrets-vault/backend";
 import { editSecretMetadata, getSecretMetadata, createOperatorSecret, deleteOperatorSecret, requireVault, rotateOperatorSecret } from "../secrets-vault/service";
-import { authContextFromRequest } from "../services/auth-context";
+import { vaultActorOf } from "../services/auth-context";
 import { ValidationError } from "../db/connection";
 import { resolveProjectAsync } from "../db/projects-async";
 import { isRecord } from "@humwick/sdk";
@@ -39,8 +39,6 @@ export const getVaultMetadataRoute: Handler = async (req) => {
   } catch (cause) { return error(cause instanceof Error ? cause.message : "vault unavailable", cause instanceof ValidationError ? 400 : 503); }
 };
 
-const operatorActor = (req: Request) => { const ctx = authContextFromRequest(req); return ctx.actor.kind === "system" ? "operator" : ctx.actor.id; };
-
 function vaultWriteError(cause: unknown): Response {
   if (cause instanceof ValidationError) return error(cause.message, 400);
   if (cause instanceof VaultError) return error(cause.message, cause.code === "exists" ? 409 : cause.code === "not_found" ? 404 : 503);
@@ -54,7 +52,7 @@ export const postVaultSecretRoute: Handler = async (req) => {
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   if (!isRecord(parsed.body)) return error("secret must be an object", 400);
-  try { return json(await createOperatorSecret(operatorActor(req), parsed.body), 201); }
+  try { return json(await createOperatorSecret(vaultActorOf(req), parsed.body), 201); }
   catch (cause) { return vaultWriteError(cause); }
 };
 
@@ -66,7 +64,7 @@ export const putVaultSecretRoute: Handler = async (req, params) => {
   if (!parsed.ok) return error(parsed.error, parsed.status);
   if (!isRecord(parsed.body)) return error("secret must be an object", 400);
   const environment = parsed.body.environment === undefined ? new URL(req.url).searchParams.get("environment") ?? undefined : parsed.body.environment;
-  try { return json(await rotateOperatorSecret(operatorActor(req), params.name!, { ...parsed.body, environment })); }
+  try { return json(await rotateOperatorSecret(vaultActorOf(req), params.name!, { ...parsed.body, environment })); }
   catch (cause) { return vaultWriteError(cause); }
 };
 
@@ -74,7 +72,7 @@ export const putVaultSecretRoute: Handler = async (req, params) => {
 export const deleteVaultSecretRoute: Handler = async (req, params) => {
   const denied = (await authorizeRoute(req, { scope: "secrets:write" }));
   if (denied) return denied;
-  try { return json(await deleteOperatorSecret(operatorActor(req), params.name!, new URL(req.url).searchParams.get("environment") ?? undefined)); }
+  try { return json(await deleteOperatorSecret(vaultActorOf(req), params.name!, new URL(req.url).searchParams.get("environment") ?? undefined)); }
   catch (cause) { return vaultWriteError(cause); }
 };
 
@@ -116,6 +114,6 @@ export const patchVaultMetadataRoute: Handler = async (req, params) => {
   if (denied) return denied;
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
-  try { return json(await editSecretMetadata(operatorActor(req), params.name!, parsed.body, new URL(req.url).searchParams.get("environment") ?? undefined)); }
+  try { return json(await editSecretMetadata(vaultActorOf(req), params.name!, parsed.body, new URL(req.url).searchParams.get("environment") ?? undefined)); }
   catch (cause) { return vaultWriteError(cause); }
 };

package/src/runtime-install.ts

@@ -0,0 +1,30 @@
+// Install Humwick packages into a runtime prefix: from the registry, or from packed tarballs
+// (`dev install`, and `init --tarball-dir` while the registry set is broken, #2680/#2324).
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const INSTALL_TIMEOUT_MS = 10 * 60_000;
+const SERVER_TARBALL = /^humwick-server-.*\.tgz$/;
+
+/** `npm install` into `prefix`; bounded, and the error carries npm's output. */
+export async function npmInstallIntoPrefix(prefix: string, specs: string[]): Promise<string> {
+  mkdirSync(prefix, { recursive: true });
+  const manifest = join(prefix, "package.json");
+  if (!existsSync(manifest)) writeFileSync(manifest, JSON.stringify({ private: true, name: "humwick-runtime" }, null, 2) + "\n", "utf8");
+  const args = ["install", "--prefix", prefix, "--no-audit", "--no-fund", "--force", ...specs];
+  try {
+    const result = await execFileAsync("npm", args, { cwd: prefix, timeout: INSTALL_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 });
+    return result.stdout.trim();
+  } catch (e) {
+    const err = e as Error & { stdout?: string; stderr?: string; killed?: boolean };
+    const tail = `${err.stdout ?? ""}\n${err.stderr ?? ""}`.trim().split("\n").slice(-20).join("\n");
+    throw new Error(`npm ${args.slice(0, 6).join(" ")} … failed${err.killed ? ` (timed out after ${INSTALL_TIMEOUT_MS / 1000} s)` : ""}:\n${tail || err.message}`);
+  }
+}
+
+export function isServerTarball(name: string): boolean {
+  return SERVER_TARBALL.test(name);
+}