@kynver-app/runtime 0.1.5 → 0.1.7

package/README.md

@@ -8,18 +8,29 @@ Standalone Kynver AgentOS execution runtime and CLI (`kynver`).
 npm run kynver:build
 npm run kynver -- setup --api-base-url http://localhost:3000 --agent-os-id <id> --repo /path/to/repo --max-workers 13
 npm run kynver -- login --api-key "$KYNVER_API_KEY"
+npm run kynver -- runner credential --agent-os-id <id>
 npm run kynver -- run create --repo /path/to/repo --name my-run
 npm run kynver -- daemon --run <runId> --agent-os-id <id> --execute
 ```
 
-Set `OPENCLAW_CRON_SECRET` or `KYNVER_RUNTIME_SECRET` for server callbacks.
+### Callback auth (scoped runner tokens)
+
+User-hosted runners should **not** use deployment-wide `OPENCLAW_CRON_SECRET` / `KYNVER_RUNTIME_SECRET`. After `kynver login`, mint a workspace-bound token:
+
+```bash
+kynver runner credential --agent-os-id <id>
+```
+
+The token (`krc1.*`) is stored in `~/.kynver/credentials` as `runnerToken` and sent as `X-Kynver-Runner-Token` on dispatch/sweep/completion/progress callbacks. It is bound to one `agentOsId` and a capability set (`tasks`, `harness`, `plans.progress`, `runtime.read`, `operator`). The server persists only a token hash plus audit metadata, so credentials can be listed, revoked, and rotated without exposing the clear token again.
+
+Global env secrets remain supported for first-party dogfood, QStash, and OpenClaw cron — server-side `verifyHarnessCallback` accepts QStash signatures, scoped tokens, or global secrets (in that precedence for non-QStash callers).
 
 ## CLI verbs
 
 ```text
 run create | list | status | dispatch | sweep
 worker start | status | tail | stop | complete
-login | setup | daemon
+login | runner credential | setup | daemon
 ```
 
 `scripts/opus-harness.mjs` is a compatibility shim that delegates to this package.

package/dist/cli.js

@@ -2,7 +2,7 @@
 
 // src/cli.ts
 import { mkdirSync as mkdirSync5 } from "node:fs";
-import path13 from "node:path";
+import path14 from "node:path";
 import { fileURLToPath } from "node:url";
 
 // src/config.ts
@@ -132,20 +132,112 @@ function saveUserConfig(config) {
   writeFileSync2(CONFIG_FILE, `${JSON.stringify(config, null, 2)}
 `, { mode: 384 });
 }
-function saveApiKey(apiKey) {
+function loadCredentialsFile() {
+  if (!existsSync2(CREDENTIALS_FILE)) return {};
+  try {
+    return JSON.parse(readFileSync2(CREDENTIALS_FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function saveCredentialsFile(parsed) {
   mkdirSync2(CONFIG_DIR, { recursive: true });
-  writeFileSync2(CREDENTIALS_FILE, `${JSON.stringify({ apiKey }, null, 2)}
+  writeFileSync2(CREDENTIALS_FILE, `${JSON.stringify(parsed, null, 2)}
 `, { mode: 384 });
 }
+function loadApiKey() {
+  if (process.env.KYNVER_API_KEY) return process.env.KYNVER_API_KEY;
+  return loadCredentialsFile().apiKey;
+}
+function saveApiKey(apiKey) {
+  saveCredentialsFile({ ...loadCredentialsFile(), apiKey });
+}
+function loadRunnerToken(agentOsId) {
+  const creds = loadCredentialsFile();
+  if (!creds.runnerToken) return void 0;
+  if (agentOsId && creds.runnerTokenAgentOsId && creds.runnerTokenAgentOsId !== agentOsId) {
+    return void 0;
+  }
+  return creds.runnerToken;
+}
+function saveRunnerToken(agentOsId, token) {
+  saveCredentialsFile({
+    ...loadCredentialsFile(),
+    runnerToken: token,
+    runnerTokenAgentOsId: agentOsId
+  });
+}
 function resolveBaseUrl(argsBaseUrl) {
   const baseUrl = argsBaseUrl || process.env.KYNVER_API_URL || process.env.OPENCLAW_CRON_FIRE_BASE_URL || loadUserConfig().apiBaseUrl;
   if (!baseUrl) failConfig("requires --base-url, KYNVER_API_URL, OPENCLAW_CRON_FIRE_BASE_URL, or ~/.kynver/config.json apiBaseUrl");
   return trimTrailingSlash(String(baseUrl));
 }
-function resolveCallbackSecret(argsSecret) {
-  const secret = argsSecret || process.env.KYNVER_RUNTIME_SECRET || process.env.OPENCLAW_CRON_SECRET;
-  if (!secret) failConfig("requires --secret, KYNVER_RUNTIME_SECRET, or OPENCLAW_CRON_SECRET");
-  return String(secret);
+function resolveCallbackSecret(argsSecret, agentOsId) {
+  const scoped = argsSecret || loadRunnerToken(agentOsId) || loadRunnerToken(loadUserConfig().agentOsId);
+  if (scoped) return String(scoped);
+  const globalSecret = process.env.KYNVER_RUNTIME_SECRET || process.env.OPENCLAW_CRON_SECRET;
+  if (globalSecret) {
+    console.warn(
+      "[kynver] using deployment-level callback secret; run `kynver runner credential --agent-os-id <id>` for a scoped token"
+    );
+    return String(globalSecret);
+  }
+  failConfig(
+    "requires --secret, a scoped runner token (`kynver runner credential`), ~/.kynver/credentials runnerToken, or (legacy) KYNVER_RUNTIME_SECRET / OPENCLAW_CRON_SECRET"
+  );
+}
+async function fetchRunnerCredential(agentOsId, opts) {
+  const apiKey = opts?.apiKey || loadApiKey();
+  if (!apiKey) throw new Error("API key required \u2014 run `kynver login` first");
+  const base = resolveBaseUrl(opts?.baseUrl);
+  const url = `${base}/api/agent-os/by-id/${encodeURIComponent(agentOsId)}/runner-credentials`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`
+    },
+    body: JSON.stringify({})
+  });
+  const text = await res.text();
+  let parsed = null;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    parsed = null;
+  }
+  if (!res.ok || !parsed?.token) {
+    throw new Error(
+      `runner credential mint failed (${res.status}): ${parsed?.error ?? text.slice(0, 200)}`
+    );
+  }
+  return parsed.token;
+}
+async function mintRunnerCredential(args) {
+  const agentOsId = (args.agentOsId ? String(args.agentOsId) : loadUserConfig().agentOsId) || "";
+  if (!agentOsId) failConfig("runner credential requires --agent-os-id or agentOsId in ~/.kynver/config.json");
+  try {
+    const token = await fetchRunnerCredential(agentOsId, {
+      baseUrl: args.baseUrl ? String(args.baseUrl) : void 0
+    });
+    saveRunnerToken(agentOsId, token);
+    console.log(
+      JSON.stringify(
+        {
+          ok: true,
+          agentOsId,
+          credentialsPath: CREDENTIALS_FILE,
+          tokenPrefix: `${token.slice(0, 12)}\u2026`,
+          note: "Scoped runner token saved; callbacks use X-Kynver-Runner-Token."
+        },
+        null,
+        2
+      )
+    );
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
 }
 function failConfig(message) {
   console.error(message);
@@ -180,13 +272,28 @@ async function runSetup(args) {
     workerProvider: typeof args.provider === "string" ? args.provider : existing.workerProvider || "claude"
   };
   saveUserConfig(config);
+  let runnerCredentialNote;
+  const apiKey = loadApiKey();
+  const agentOsId = config.agentOsId;
+  if (apiKey && agentOsId) {
+    try {
+      const token = await fetchRunnerCredential(agentOsId, {
+        baseUrl: typeof args.apiBaseUrl === "string" ? args.apiBaseUrl : config.apiBaseUrl,
+        apiKey
+      });
+      saveRunnerToken(agentOsId, token);
+      runnerCredentialNote = "Scoped runner token minted and saved to ~/.kynver/credentials.";
+    } catch {
+      runnerCredentialNote = "Runner token not minted (server offline or master secret unset). Run `kynver runner credential` after deploy.";
+    }
+  }
   console.log(
     JSON.stringify(
       {
         ok: true,
         configPath: CONFIG_FILE,
         config,
-        note: "Set worker limit once with --max-workers N (or omit to auto-size from RAM). Advanced RAM tuning stays internal."
+        note: runnerCredentialNote ?? "Set worker limit once with --max-workers N (or omit to auto-size from RAM). Run `kynver login` + `kynver runner credential` for scoped callbacks."
       },
       null,
       2
@@ -200,15 +307,27 @@ async function runLogin(args) {
   console.log(JSON.stringify({ ok: true, credentialsPath: CREDENTIALS_FILE }, null, 2));
 }
 
+// src/callback-headers.ts
+function buildHarnessCallbackHeaders(secret) {
+  const trimmed = String(secret).trim();
+  if (trimmed.startsWith("krc1.")) {
+    return {
+      "Content-Type": "application/json",
+      "X-Kynver-Runner-Token": trimmed
+    };
+  }
+  return {
+    "Content-Type": "application/json",
+    "X-OpenClaw-Cron-Secret": trimmed,
+    "X-Kynver-Runtime-Secret": trimmed
+  };
+}
+
 // src/callbacks.ts
 async function postJson(url, secret, body) {
   const res = await fetch(url, {
     method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "X-OpenClaw-Cron-Secret": String(secret),
-      "X-Kynver-Runtime-Secret": String(secret)
-    },
+    headers: buildHarnessCallbackHeaders(secret),
     body: JSON.stringify(body)
   });
   let response = null;
@@ -222,10 +341,7 @@ async function postJson(url, secret, body) {
 async function getJson(url, secret) {
   const res = await fetch(url, {
     method: "GET",
-    headers: {
-      "X-OpenClaw-Cron-Secret": String(secret),
-      "X-Kynver-Runtime-Secret": String(secret)
-    }
+    headers: buildHarnessCallbackHeaders(secret)
   });
   let response = null;
   try {
@@ -243,12 +359,12 @@ var DEFAULT_CRITICAL_FREE_BYTES = 15 * 1024 * 1024 * 1024;
 var DEFAULT_MAX_USED_PERCENT = 80;
 var DEFAULT_HARD_MAX_USED_PERCENT = 90;
 function observeRunnerDiskGate(input = {}) {
-  const path14 = input.diskPath?.trim() || "/";
+  const path15 = input.diskPath?.trim() || "/";
   const warnBelowBytes = input.diskFreeWarnBytes ?? DEFAULT_WARN_FREE_BYTES;
   const criticalBelowBytes = input.diskFreeCriticalBytes ?? DEFAULT_CRITICAL_FREE_BYTES;
   const maxUsedPercent = input.diskMaxUsedPercent ?? DEFAULT_MAX_USED_PERCENT;
   const hardMaxUsedPercent = input.diskHardMaxUsedPercent ?? DEFAULT_HARD_MAX_USED_PERCENT;
-  const stats = statfsSync(path14);
+  const stats = statfsSync(path15);
   const freeBytes = Number(stats.bavail) * Number(stats.bsize);
   const totalBytes = Number(stats.blocks) * Number(stats.bsize);
   const usedPercent = totalBytes > 0 ? (totalBytes - freeBytes) / totalBytes * 100 : 100;
@@ -268,7 +384,7 @@ function observeRunnerDiskGate(input = {}) {
   }
   return {
     ok,
-    path: path14,
+    path: path15,
     freeBytes,
     totalBytes,
     usedPercent,
@@ -874,6 +990,7 @@ function spawnWorkerProcess(run, opts) {
     ownedPaths: opts.ownedPaths,
     ...opts.agentOsId ? { agentOsId: String(opts.agentOsId) } : {},
     ...opts.taskId ? { taskId: String(opts.taskId) } : {},
+    ...opts.planId ? { planId: String(opts.planId) } : {},
     ...opts.leaseOwner ? { leaseOwner: String(opts.leaseOwner) } : {},
     ...opts.dispatched ? { dispatched: true } : {},
     startedAt: (/* @__PURE__ */ new Date()).toISOString()
@@ -940,7 +1057,7 @@ async function dispatchRun(args) {
     const run = loadRun(String(required(String(args.run || ""), "--run")));
     const agentOsId = String(required(String(args.agentOsId || ""), "--agent-os-id"));
     const base = resolveBaseUrl(args.baseUrl ? String(args.baseUrl) : void 0);
-    const secret = resolveCallbackSecret(args.secret ? String(args.secret) : void 0);
+    const secret = resolveCallbackSecret(args.secret ? String(args.secret) : void 0, agentOsId);
     const execute = args.execute === true || args.execute === "true";
     const dryRun = !execute;
     const leaseOwner = `openclaw-harness:${run.id}`;
@@ -1014,6 +1131,7 @@ async function dispatchRun(args) {
       const task = decision.task;
       const name = safeSlug(`t-${task.id}-a${task.attempt}`);
       try {
+        const planId = task.planId ? String(task.planId) : void 0;
         const worker = spawnWorkerProcess(run, {
           name,
           task: buildDispatchTaskText(task, agentOsId),
@@ -1021,6 +1139,7 @@ async function dispatchRun(args) {
           model: args.model ? String(args.model) : void 0,
           agentOsId,
           taskId: String(task.id),
+          planId,
           leaseOwner,
           dispatched: true
         });
@@ -1082,7 +1201,7 @@ async function sweepRun(args) {
     const run = loadRun(String(required(String(args.run || ""), "--run")));
     const agentOsId = String(required(String(args.agentOsId || ""), "--agent-os-id"));
     const base = resolveBaseUrl(args.baseUrl ? String(args.baseUrl) : void 0);
-    const secret = resolveCallbackSecret(args.secret ? String(args.secret) : void 0);
+    const secret = resolveCallbackSecret(args.secret ? String(args.secret) : void 0, agentOsId);
     const leaseOwner = `openclaw-harness:${run.id}`;
     const releasedLocalOrphans = [];
     for (const name of Object.keys(run.workers || {})) {
@@ -1200,7 +1319,7 @@ async function tryCompleteWorker(args) {
     return { ok: true, skipped: true, reason: "worker-not-finished" };
   }
   const base = resolveBaseUrl(args.baseUrl ? String(args.baseUrl) : void 0);
-  const secret = resolveCallbackSecret(args.secret ? String(args.secret) : void 0);
+  const secret = resolveCallbackSecret(args.secret ? String(args.secret) : void 0, agentOsId);
   const url = `${base}/api/agent-os/by-id/${encodeURIComponent(agentOsId)}/harness/completion`;
   const body = {
     source: "openclaw-harness",
@@ -1214,11 +1333,7 @@ async function tryCompleteWorker(args) {
   };
   const res = await fetch(url, {
     method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "X-OpenClaw-Cron-Secret": secret,
-      "X-Kynver-Runtime-Secret": secret
-    },
+    headers: buildHarnessCallbackHeaders(secret),
     body: JSON.stringify(body)
   });
   let parsed = null;
@@ -1353,12 +1468,57 @@ function stopWorker(args) {
 }
 
 // src/pipeline-tick.ts
+import path13 from "node:path";
+
+// src/plan-progress-daemon-sync.ts
 import path12 from "node:path";
 
+// src/plan-progress-sync.ts
+async function syncPlanProgress(args) {
+  const base = resolveBaseUrl(args.baseUrl);
+  const secret = resolveCallbackSecret(args.secret);
+  const url = `${base}/api/agent-os/by-id/${encodeURIComponent(args.agentOsId)}/tasks/${encodeURIComponent(args.taskId)}/plan-progress-sync`;
+  const res = await postJson(url, secret, {
+    phase: args.phase,
+    taskId: args.taskId,
+    blocker: args.blocker,
+    artifact: args.artifact
+  });
+  return { ok: res.ok, status: res.status, response: res.response };
+}
+
+// src/plan-progress-daemon-sync.ts
+async function syncActiveWorkerPlanProgress(runId, args) {
+  const run = loadRun(runId);
+  const agentOsId = String(args.agentOsId || "");
+  if (!agentOsId) return [];
+  const outcomes = [];
+  for (const name of Object.keys(run.workers || {})) {
+    const worker = readJson(
+      path12.join(runDirectory(run.id), "workers", safeSlug(name), "worker.json"),
+      null
+    );
+    if (!worker?.dispatched || !worker.taskId) continue;
+    const status = computeWorkerStatus(worker);
+    if (status.heartbeatBlocker) {
+      const res = await syncPlanProgress({
+        agentOsId,
+        taskId: worker.taskId,
+        phase: "heartbeat_blocker",
+        blocker: status.heartbeatBlocker,
+        baseUrl: args.baseUrl ? String(args.baseUrl) : void 0,
+        secret: args.secret ? String(args.secret) : void 0
+      });
+      outcomes.push({ worker: name, phase: "heartbeat_blocker", ok: res.ok });
+    }
+  }
+  return outcomes;
+}
+
 // src/workspace-runtime-config.ts
 async function fetchWorkspaceRuntimePreferences(agentOsId, args) {
   const base = resolveBaseUrl(args.baseUrl ? String(args.baseUrl) : void 0);
-  const secret = resolveCallbackSecret(args.secret ? String(args.secret) : void 0);
+  const secret = resolveCallbackSecret(args.secret ? String(args.secret) : void 0, agentOsId);
   const url = `${base}/api/agent-os/by-id/${encodeURIComponent(agentOsId)}/runtime`;
   try {
     const res = await getJson(url, secret);
@@ -1382,7 +1542,7 @@ async function completeFinishedWorkers(runId, args) {
   const outcomes = [];
   for (const name of Object.keys(run.workers || {})) {
     const worker = readJson(
-      path12.join(runDirectory(run.id), "workers", safeSlug(name), "worker.json"),
+      path13.join(runDirectory(run.id), "workers", safeSlug(name), "worker.json"),
       null
     );
     if (!worker?.dispatched || !worker.taskId) continue;
@@ -1401,7 +1561,7 @@ async function completeFinishedWorkers(runId, args) {
 }
 async function postOperatorTick(agentOsId, runId, resourceGate, args) {
   const base = resolveBaseUrl(args.baseUrl ? String(args.baseUrl) : void 0);
-  const secret = resolveCallbackSecret(args.secret ? String(args.secret) : void 0);
+  const secret = resolveCallbackSecret(args.secret ? String(args.secret) : void 0, agentOsId);
   const url = `${base}/api/agent-os/by-id/${encodeURIComponent(agentOsId)}/operator/tick`;
   const res = await postJson(url, secret, {
     agentOsId,
@@ -1417,6 +1577,7 @@ async function runPipelineTick(args) {
   const execute = args.execute !== false && args.execute !== "false";
   runStatus({ run: runId });
   const completedWorkers = await completeFinishedWorkers(runId, args);
+  const planProgressSync = await syncActiveWorkerPlanProgress(runId, args);
   const workspacePrefs = await fetchWorkspaceRuntimePreferences(agentOsId, args);
   const resourceGate = observeRunnerResourceGate({
     runId,
@@ -1456,6 +1617,7 @@ async function runPipelineTick(args) {
     execute,
     resourceGate,
     completedWorkers,
+    planProgressSync,
     operatorTick,
     sweep,
     dispatch,
@@ -1523,7 +1685,7 @@ async function emitPlanProgress(args) {
     evidence.push(parseEvidenceArg(rawEvidence));
   }
   const base = resolveBaseUrl(args.baseUrl ? String(args.baseUrl) : void 0);
-  const secret = resolveCallbackSecret(args.secret ? String(args.secret) : void 0);
+  const secret = resolveCallbackSecret(args.secret ? String(args.secret) : void 0, agentOsId);
   const url = `${base}/api/agent-os/by-id/${encodeURIComponent(agentOsId)}/plans/${encodeURIComponent(planId)}/progress-events`;
   const cfg = loadUserConfig();
   const provider = cfg.workerProvider ? `provider:${cfg.workerProvider}` : void 0;
@@ -1542,10 +1704,7 @@ async function emitPlanProgress(args) {
   };
   const res = await fetch(url, {
     method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "X-OpenClaw-Cron-Secret": secret
-    },
+    headers: buildHarnessCallbackHeaders(secret),
     body: JSON.stringify(body)
   });
   const text = await res.text();
@@ -1611,6 +1770,7 @@ function usage(code = 0) {
     [
       "Usage:",
       "  kynver login --api-key KEY",
+      "  kynver runner credential [--agent-os-id ID] [--base-url URL]",
       "  kynver setup [--api-base-url URL] [--agent-os-id ID] [--agent-os-slug SLUG] [--repo PATH] [--max-workers N] [--provider claude|cursor]",
       "  kynver daemon --run RUN_ID --agent-os-id AOS_ID [--execute] [--interval-ms MS]",
       "  kynver run create --repo /path/repo [--name name] [--base origin/main]",
@@ -1634,7 +1794,7 @@ async function main(argv = process.argv.slice(2)) {
   const scope = argv.shift();
   let action;
   let rest;
-  if (scope === "run" || scope === "worker" || scope === "plan") {
+  if (scope === "run" || scope === "worker" || scope === "plan" || scope === "runner") {
     action = argv.shift();
     rest = argv;
   } else {
@@ -1645,6 +1805,7 @@ async function main(argv = process.argv.slice(2)) {
   mkdirSync5(runsDir, { recursive: true });
   mkdirSync5(worktreesDir, { recursive: true });
   if (scope === "login") return void await runLogin(args);
+  if (scope === "runner" && action === "credential") return void await mintRunnerCredential(args);
   if (scope === "setup") return void await runSetup(args);
   if (scope === "daemon") return void await runDaemon(args);
   if (scope === "plan" && action === "progress") return void await emitPlanProgress(args);
@@ -1661,7 +1822,7 @@ async function main(argv = process.argv.slice(2)) {
   if (scope === "worker" && action === "complete") return void await completeWorker(args);
   unknownCommand(scope, action);
 }
-var isCliEntry = process.argv[1] && path13.resolve(process.argv[1]) === path13.resolve(fileURLToPath(import.meta.url));
+var isCliEntry = process.argv[1] && path14.resolve(process.argv[1]) === path14.resolve(fileURLToPath(import.meta.url));
 if (isCliEntry) {
   void main().catch((error) => {
     console.error(error);