@chrysb/alphaclaw 0.4.6-beta.7 → 0.4.6-beta.9

package/lib/server/commands.js

@@ -14,6 +14,7 @@ const createCommands = ({ gatewayEnv }) => {
       console.log(
         `[onboard] Running: ${cmd
           .replace(/ghp_[^\s"]+/g, "***")
+          .replace(/github_pat_[^\s"]+/g, "***")
           .replace(/sk-[^\s"]+/g, "***")
           .slice(0, 200)}`,
       );

package/lib/server/constants.js

@@ -193,7 +193,6 @@ const kKnownVars = [
     key: "GITHUB_TOKEN",
     label: "GitHub Access Token",
     group: "github",
-    hint: "Create one with repo scope at github.com/settings/tokens",
   },
   {
     key: "GITHUB_WORKSPACE_REPO",

package/lib/server/doctor/bootstrap-context.js

@@ -0,0 +1,191 @@
+const fs = require("fs");
+const path = require("path");
+
+const kDoctorBootstrapMaxChars = 20000;
+const kDoctorBootstrapTotalMaxChars = 150000;
+const kDoctorBootstrapNearLimitRatio = 0.9;
+const kDoctorContextTruncationGuidance =
+  "OpenClaw trims oversized injected files by keeping the first 70%, keeping the last 20%, and cutting the middle 10% without a warning.";
+
+const kDoctorRootContextFiles = [
+  { path: "AGENTS.md", injectMode: "always" },
+  { path: "SOUL.md", injectMode: "always" },
+  { path: "TOOLS.md", injectMode: "always" },
+  { path: "IDENTITY.md", injectMode: "always" },
+  { path: "USER.md", injectMode: "always" },
+  { path: "HEARTBEAT.md", injectMode: "always" },
+  { path: "BOOTSTRAP.md", injectMode: "first_run_only" },
+];
+
+const kDoctorBootstrapExtraFiles = [
+  { path: "hooks/bootstrap/AGENTS.md", injectMode: "always" },
+  { path: "hooks/bootstrap/TOOLS.md", injectMode: "always" },
+];
+
+const kDoctorBootstrapContextFiles = [...kDoctorRootContextFiles, ...kDoctorBootstrapExtraFiles];
+
+const readWorkspaceFileChars = (workspaceRoot, relativePath) => {
+  const fullPath = path.join(workspaceRoot, relativePath);
+  try {
+    const content = fs.readFileSync(fullPath, "utf8");
+    return {
+      exists: true,
+      chars: content.length,
+    };
+  } catch {
+    return {
+      exists: false,
+      chars: 0,
+    };
+  }
+};
+
+const analyzeBootstrapContext = ({
+  workspaceRoot = "",
+  bootstrapMaxChars = kDoctorBootstrapMaxChars,
+  bootstrapTotalMaxChars = kDoctorBootstrapTotalMaxChars,
+} = {}) => {
+  const files = kDoctorBootstrapContextFiles.map((spec) => {
+    const fileState = readWorkspaceFileChars(workspaceRoot, spec.path);
+    const rawChars = fileState.chars;
+    const fileLimitChars = Math.min(rawChars, bootstrapMaxChars);
+    const nearFileLimit = rawChars > 0 && rawChars >= Math.floor(bootstrapMaxChars * kDoctorBootstrapNearLimitRatio);
+    return {
+      ...spec,
+      exists: fileState.exists,
+      rawChars,
+      fileLimitChars,
+      injectedChars: 0,
+      truncatedByFileLimit: rawChars > bootstrapMaxChars,
+      truncatedByTotalLimit: false,
+      truncated: rawChars > bootstrapMaxChars,
+      nearFileLimit: nearFileLimit && rawChars <= bootstrapMaxChars,
+      active: spec.injectMode === "always",
+      reason: rawChars > bootstrapMaxChars ? "file_limit" : "",
+    };
+  });
+
+  let injectedTotalChars = 0;
+  for (const file of files) {
+    if (!file.active || !file.exists) continue;
+    const remainingChars = Math.max(0, bootstrapTotalMaxChars - injectedTotalChars);
+    file.injectedChars = Math.min(file.fileLimitChars, remainingChars);
+    file.truncatedByTotalLimit = file.fileLimitChars > file.injectedChars;
+    file.truncated = file.truncatedByFileLimit || file.truncatedByTotalLimit;
+    if (file.truncatedByFileLimit && file.truncatedByTotalLimit) {
+      file.reason = "file_and_total_limit";
+    } else if (file.truncatedByFileLimit) {
+      file.reason = "file_limit";
+    } else if (file.truncatedByTotalLimit) {
+      file.reason = "total_limit";
+    }
+    injectedTotalChars += file.injectedChars;
+  }
+
+  const activeFiles = files.filter((file) => file.active && file.exists);
+  const activeTruncatedFiles = activeFiles.filter((file) => file.truncated);
+  const activeNearLimitFiles = activeFiles.filter((file) => file.nearFileLimit && !file.truncated);
+  const inactiveTruncatedFiles = files.filter((file) => !file.active && file.exists && file.truncated);
+  const hasTotalLimitTruncation = activeTruncatedFiles.some(
+    (file) => file.reason === "total_limit" || file.reason === "file_and_total_limit",
+  );
+
+  return {
+    bootstrapMaxChars,
+    bootstrapTotalMaxChars,
+    truncationGuidance: kDoctorContextTruncationGuidance,
+    files,
+    activeFiles,
+    activeRawChars: activeFiles.reduce((sum, file) => sum + file.rawChars, 0),
+    activeInjectedChars: activeFiles.reduce((sum, file) => sum + file.injectedChars, 0),
+    hasActiveTruncation: activeTruncatedFiles.length > 0,
+    hasActiveNearLimitFiles: activeNearLimitFiles.length > 0,
+    hasActiveWarnings: activeTruncatedFiles.length > 0 || activeNearLimitFiles.length > 0,
+    hasAnyTruncation: activeTruncatedFiles.length > 0 || inactiveTruncatedFiles.length > 0,
+    activeTruncatedFiles,
+    activeNearLimitFiles,
+    inactiveTruncatedFiles,
+    hasTotalLimitTruncation,
+    totalLimitReached: injectedTotalChars >= bootstrapTotalMaxChars,
+  };
+};
+
+const formatChars = (value = 0) => `${Number(value || 0).toLocaleString()} chars`;
+
+const buildBootstrapTruncationCards = (bootstrapContext = null) => {
+  if (!bootstrapContext?.hasActiveTruncation) return [];
+
+  const cards = bootstrapContext.activeTruncatedFiles
+    .filter((file) => file.reason === "file_limit")
+    .map((file) => ({
+      priority: "P0",
+      category: "project context",
+      title: `${file.path} is being truncated in Project Context`,
+      summary:
+        `${file.path} is ${formatChars(file.rawChars)}, above the per-file Project Context limit ` +
+        `of ${formatChars(bootstrapContext.bootstrapMaxChars)}. The agent is not seeing the full file.`,
+      recommendation:
+        `Move the most important rules to the top of ${file.path}, shorten or split low-priority content, ` +
+        `and increase OpenClaw's bootstrap limits if this file legitimately needs more room. ` +
+        kDoctorContextTruncationGuidance,
+      evidence: [
+        { type: "path", path: file.path },
+        {
+          type: "text",
+          text:
+            `Raw size: ${formatChars(file.rawChars)}. ` +
+            `Per-file limit: ${formatChars(bootstrapContext.bootstrapMaxChars)}.`,
+        },
+      ],
+      targetPaths: [{ path: file.path }],
+      fixPrompt:
+        `Reorganize ${file.path} so the most important instructions appear at the top and reduce unnecessary length. ` +
+        `Do not change unrelated behavior.`,
+      status: "open",
+    }));
+
+  const totalLimitedFiles = bootstrapContext.activeTruncatedFiles.filter(
+    (file) => file.reason === "total_limit" || file.reason === "file_and_total_limit",
+  );
+  if (totalLimitedFiles.length > 0) {
+    cards.unshift({
+      priority: "P0",
+      category: "project context",
+      title: "Project Context total bootstrap limit is truncating injected files",
+      summary:
+        `Injected workspace guidance needs ${formatChars(bootstrapContext.activeRawChars)} raw across active ` +
+        `Project Context files, exceeding the total bootstrap budget of ` +
+        `${formatChars(bootstrapContext.bootstrapTotalMaxChars)}.`,
+      recommendation:
+        `Reduce total Project Context size across injected guidance files, keep critical instructions near the top, ` +
+        `and raise OpenClaw's total bootstrap budget if the workspace legitimately needs more injected guidance. ` +
+        kDoctorContextTruncationGuidance,
+      evidence: totalLimitedFiles.map((file) => ({
+        type: "text",
+        text:
+          `${file.path}: raw ${formatChars(file.rawChars)}, injected ${formatChars(file.injectedChars)} ` +
+          `before the total limit stopped more content from being included.`,
+      })),
+      targetPaths: totalLimitedFiles.map((file) => ({ path: file.path })),
+      fixPrompt:
+        `Reduce the combined size of the affected Project Context files and keep the most important instructions near the top. ` +
+        `Only edit the files listed in the finding.`,
+      status: "open",
+    });
+  }
+
+  return cards;
+};
+
+module.exports = {
+  analyzeBootstrapContext,
+  buildBootstrapTruncationCards,
+  formatChars,
+  kDoctorBootstrapContextFiles,
+  kDoctorBootstrapExtraFiles,
+  kDoctorBootstrapMaxChars,
+  kDoctorBootstrapNearLimitRatio,
+  kDoctorBootstrapTotalMaxChars,
+  kDoctorContextTruncationGuidance,
+  kDoctorRootContextFiles,
+};

package/lib/server/doctor/prompt.js

@@ -1,6 +1,17 @@
+const {
+  kDoctorBootstrapExtraFiles,
+  kDoctorBootstrapMaxChars,
+  kDoctorBootstrapTotalMaxChars,
+  kDoctorContextTruncationGuidance,
+  kDoctorRootContextFiles,
+} = require("./bootstrap-context");
+
 const renderList = (items = []) =>
   items.length ? items.map((item) => `- ${item}`).join("\n") : "- (none)";
 
+const renderContextFileList = (files = []) =>
+  files.map((file) => `\`${file.path}\``).join(", ");
+
 const renderResolvedCards = (cards = []) => {
   if (!cards.length) return "";
   const lines = cards.map(
@@ -37,10 +48,15 @@ Important:
 - Return ONLY valid JSON. No markdown fences. No extra prose.
 
 OpenClaw context injection:
-- OpenClaw automatically injects a fixed set of named workspace files into the agent's context window ("Project Context") on every turn. The exact set is: \`AGENTS.md\`, \`SOUL.md\`, \`TOOLS.md\`, \`IDENTITY.md\`, \`USER.md\`, \`HEARTBEAT.md\`, and \`BOOTSTRAP.md\` (first-run only).
-- Only these specific files are auto-injected. Other \`.md\` files at the workspace root (e.g. INTERESTS.md, MEMORY.md, README.md) are NOT injected and must be explicitly read by the agent.
-- Do not flag auto-injected files as orphaned or unreferenced — they are loaded by the runtime, not by explicit file references in AGENTS.md.
-- Additionally, AlphaClaw injects bootstrap files from \`hooks/bootstrap/\` (e.g. AGENTS.md, TOOLS.md) as extra context on every turn.
+- OpenClaw automatically injects these workspace files into the agent's Project Context: ${renderContextFileList(
+    kDoctorRootContextFiles,
+  )}.
+- \`BOOTSTRAP.md\` is first-run only; the others above are injected on normal turns when present.
+- Additionally, AlphaClaw injects these extra bootstrap files on normal turns when present: ${renderContextFileList(
+    kDoctorBootstrapExtraFiles,
+  )}.
+- Large injected files are truncated per-file at ${kDoctorBootstrapMaxChars} chars by default, and total bootstrap injection across files is capped at ${kDoctorBootstrapTotalMaxChars} chars by default.
+- ${kDoctorContextTruncationGuidance}
 
 OpenClaw default context:
 - \`AGENTS.md\` is the workspace home file in the default OpenClaw template. It may intentionally include first-run instructions, session-startup guidance, memory conventions, safety rules, tool pointers, and optional behavioral guidance.

package/lib/server/doctor/service.js

@@ -1,5 +1,9 @@
 const fs = require("fs");
 const path = require("path");
+const {
+  analyzeBootstrapContext,
+  buildBootstrapTruncationCards,
+} = require("./bootstrap-context");
 const { buildDoctorPrompt } = require("./prompt");
 const { normalizeDoctorResult } = require("./normalize");
 const { calculateWorkspaceDelta, computeWorkspaceSnapshot } = require("./workspace-fingerprint");
@@ -137,6 +141,7 @@ const createDoctorService = ({
   };
 
   const buildStatus = () => {
+    const bootstrapContext = analyzeBootstrapContext({ workspaceRoot });
     const recentRuns = listDoctorRuns({ limit: 10 });
     const latestRun = recentRuns[0] || null;
     const latestCompletedRun =
@@ -179,6 +184,7 @@ const createDoctorService = ({
       lastRunAgeMs,
       needsInitialRun: !latestCompletedRun,
       stale,
+      bootstrapContext,
       changeSummary: {
         ...delta,
         hasBaseline: hasManifestBaseline,
@@ -245,10 +251,14 @@ const createDoctorService = ({
         console.error(`[doctor] run ${runId} stderr end`);
         throw error;
       }
-      captureEvidenceSnippets(normalizedResult.cards, workspaceRoot);
+      const bootstrapTruncationCards = buildBootstrapTruncationCards(
+        analyzeBootstrapContext({ workspaceRoot }),
+      );
+      const cards = [...bootstrapTruncationCards, ...normalizedResult.cards];
+      captureEvidenceSnippets(cards, workspaceRoot);
       insertDoctorCards({
         runId,
-        cards: normalizedResult.cards,
+        cards,
       });
       completeDoctorRun({
         id: runId,
@@ -342,7 +352,11 @@ const createDoctorService = ({
       throw new Error("Doctor import requires raw output");
     }
     const normalizedResult = normalizeDoctorResult(normalizedRawOutput);
-    captureEvidenceSnippets(normalizedResult.cards, workspaceRoot);
+    const bootstrapTruncationCards = buildBootstrapTruncationCards(
+      analyzeBootstrapContext({ workspaceRoot }),
+    );
+    const cards = [...bootstrapTruncationCards, ...normalizedResult.cards];
+    captureEvidenceSnippets(cards, workspaceRoot);
     const workspaceSnapshot = getCurrentWorkspaceSnapshot();
     const runId = createDoctorRun({
       status: kDoctorRunStatus.completed,
@@ -354,7 +368,7 @@ const createDoctorService = ({
     });
     insertDoctorCards({
       runId,
-      cards: normalizedResult.cards,
+      cards,
     });
     completeDoctorRun({
       id: runId,

package/lib/server/gateway.js

@@ -3,6 +3,7 @@ const { spawn, execSync } = require("child_process");
 const fs = require("fs");
 const net = require("net");
 const {
+  ALPHACLAW_DIR,
   OPENCLAW_DIR,
   GATEWAY_HOST,
   GATEWAY_PORT,
@@ -48,51 +49,25 @@ const gatewayEnv = () => ({
   XDG_CONFIG_HOME: OPENCLAW_DIR,
 });
 
-const hasOnboardingModelConfig = () => {
-  const configPath = `${OPENCLAW_DIR}/openclaw.json`;
-  if (!fs.existsSync(configPath)) return false;
-  try {
-    const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
-    const primaryModel = String(
-      config?.agents?.defaults?.model?.primary || "",
-    ).trim();
-    return primaryModel.includes("/");
-  } catch {
-    return false;
-  }
-};
-
-const hasLegacyOnboardingArtifacts = () => fs.existsSync(kControlUiSkillPath);
-
 const writeOnboardingMarker = (reason) => {
-  try {
-    fs.mkdirSync(path.dirname(kOnboardingMarkerPath), { recursive: true });
-    fs.writeFileSync(
-      kOnboardingMarkerPath,
-      JSON.stringify(
-        {
-          onboarded: true,
-          reason: String(reason || "unknown"),
-          markedAt: new Date().toISOString(),
-        },
-        null,
-        2,
-      ),
-    );
-    return true;
-  } catch (err) {
-    console.error(`[alphaclaw] Failed to write onboarding marker: ${err.message}`);
-    return false;
-  }
+  fs.mkdirSync(ALPHACLAW_DIR, { recursive: true });
+  fs.writeFileSync(
+    kOnboardingMarkerPath,
+    JSON.stringify(
+      {
+        onboarded: true,
+        reason,
+        markedAt: new Date().toISOString(),
+      },
+      null,
+      2,
+    ),
+  );
 };
 
 const isOnboarded = () => {
   if (fs.existsSync(kOnboardingMarkerPath)) return true;
-  if (hasOnboardingModelConfig()) {
-    writeOnboardingMarker("config_primary_model");
-    return true;
-  }
-  if (hasLegacyOnboardingArtifacts()) {
+  if (fs.existsSync(kControlUiSkillPath)) {
     writeOnboardingMarker("legacy_artifact_backfill");
     return true;
   }

package/lib/server/onboarding/github.js

@@ -1,3 +1,12 @@
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const crypto = require("crypto");
+const {
+  kImportTempPrefix,
+  isValidImportTempDir,
+} = require("./import/import-temp");
+
 const buildGithubHeaders = (githubToken) => ({
   Authorization: `token ${githubToken}`,
   "User-Agent": "openclaw-railway",
@@ -14,9 +23,18 @@ const parseGithubErrorMessage = async (response) => {
   return response.statusText || `HTTP ${response.status}`;
 };
 
-const verifyGithubRepoForOnboarding = async ({ repoUrl, githubToken }) => {
+const isClassicPat = (token) => String(token || "").startsWith("ghp_");
+const isFineGrainedPat = (token) =>
+  String(token || "").startsWith("github_pat_");
+
+const verifyGithubRepoForOnboarding = async ({
+  repoUrl,
+  githubToken,
+  mode = "new",
+}) => {
   const ghHeaders = buildGithubHeaders(githubToken);
   const [repoOwner] = String(repoUrl || "").split("/", 1);
+  const isExisting = mode === "existing";
 
   try {
     const userRes = await fetch("https://api.github.com/user", {
@@ -30,25 +48,28 @@ const verifyGithubRepoForOnboarding = async ({ repoUrl, githubToken }) => {
         error: `Cannot verify GitHub token: ${details}`,
       };
     }
-    const oauthScopes = (userRes.headers?.get?.("x-oauth-scopes") || "")
-      .toLowerCase()
-      .split(",")
-      .map((s) => s.trim())
-      .filter(Boolean);
-    if (
-      oauthScopes.length > 0 &&
-      !oauthScopes.includes("repo") &&
-      !oauthScopes.includes("public_repo")
-    ) {
-      return {
-        ok: false,
-        status: 400,
-        error: `Your token needs the "repo" scope to create repositories. Current scopes: ${oauthScopes.join(", ")}`,
-      };
+    if (isClassicPat(githubToken)) {
+      const oauthScopes = (userRes.headers?.get?.("x-oauth-scopes") || "")
+        .toLowerCase()
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+      if (
+        oauthScopes.length > 0 &&
+        !oauthScopes.includes("repo") &&
+        !oauthScopes.includes("public_repo")
+      ) {
+        return {
+          ok: false,
+          status: 400,
+          error: `Your token needs the "repo" scope. Current scopes: ${oauthScopes.join(", ")}`,
+        };
+      }
     }
     const authedUser = await userRes.json().catch(() => ({}));
     const authedLogin = String(authedUser?.login || "").trim();
     if (
+      !isExisting &&
       repoOwner &&
       authedLogin &&
       repoOwner.toLowerCase() !== authedLogin.toLowerCase()
@@ -56,7 +77,7 @@ const verifyGithubRepoForOnboarding = async ({ repoUrl, githubToken }) => {
       return {
         ok: false,
         status: 400,
-        error: `Workspace repo owner must match your token user "${authedLogin}"`,
+        error: `New workspace repo owner must match your token user "${authedLogin}"`,
       };
     }
 
@@ -64,6 +85,13 @@ const verifyGithubRepoForOnboarding = async ({ repoUrl, githubToken }) => {
       headers: ghHeaders,
     });
     if (checkRes.status === 404) {
+      if (isExisting) {
+        return {
+          ok: false,
+          status: 400,
+          error: `Repository "${repoUrl}" not found. Check the repo name and token permissions.`,
+        };
+      }
       return { ok: true, repoExists: false, repoIsEmpty: false };
     }
     if (checkRes.ok) {
@@ -75,10 +103,13 @@ const verifyGithubRepoForOnboarding = async ({ repoUrl, githubToken }) => {
         return { ok: true, repoExists: true, repoIsEmpty: true };
       }
       if (commitsRes.ok) {
+        if (isExisting) {
+          return { ok: true, repoExists: true, repoIsEmpty: false };
+        }
         return {
           ok: false,
           status: 400,
-          error: `Repository "${repoUrl}" already exists and is not empty.`,
+          error: `Repository "${repoUrl}" already exists and is not empty. Did you mean to use "Import existing setup"?`,
         };
       }
       const commitCheckDetails = await parseGithubErrorMessage(commitsRes);
@@ -90,6 +121,13 @@ const verifyGithubRepoForOnboarding = async ({ repoUrl, githubToken }) => {
     }
 
     const details = await parseGithubErrorMessage(checkRes);
+    if (isFineGrainedPat(githubToken) && checkRes.status === 403) {
+      return {
+        ok: false,
+        status: 400,
+        error: `Your fine-grained token needs Contents (read/write) and Metadata (read) permissions for "${repoUrl}".`,
+      };
+    }
     return {
       ok: false,
       status: 400,
@@ -150,4 +188,67 @@ const ensureGithubRepoAccessible = async ({
   }
 };
 
-module.exports = { ensureGithubRepoAccessible, verifyGithubRepoForOnboarding };
+const cloneRepoToTemp = async ({ repoUrl, githubToken, shellCmd }) => {
+  const tempId = crypto.randomUUID().slice(0, 8);
+  const tempDir = path.join(os.tmpdir(), `${kImportTempPrefix}${tempId}`);
+  const askPassPath = path.join(
+    os.tmpdir(),
+    `alphaclaw-import-askpass-${tempId}.sh`,
+  );
+
+  try {
+    fs.writeFileSync(
+      askPassPath,
+      [
+        "#!/bin/sh",
+        'case "$1" in',
+        '  *Username*) printf "%s\\n" "x-access-token" ;;',
+        '  *) printf "%s\\n" "$ALPHACLAW_GITHUB_TOKEN" ;;',
+        "esac",
+        "",
+      ].join("\n"),
+      { mode: 0o700 },
+    );
+    await shellCmd(
+      `git clone --depth=1 "https://github.com/${repoUrl}.git" "${tempDir}"`,
+      {
+        timeout: 60000,
+        env: {
+          ...process.env,
+          GIT_ASKPASS: askPassPath,
+          GIT_TERMINAL_PROMPT: "0",
+          ALPHACLAW_GITHUB_TOKEN: githubToken,
+        },
+      },
+    );
+    console.log(`[onboard] Cloned ${repoUrl} to ${tempDir}`);
+    return { ok: true, tempDir };
+  } catch (e) {
+    return {
+      ok: false,
+      error: `Failed to clone repo: ${e.message}`,
+    };
+  } finally {
+    try {
+      fs.rmSync(askPassPath, { force: true });
+    } catch {}
+  }
+};
+
+const cleanupTempClone = (tempDir) => {
+  try {
+    if (isValidImportTempDir(tempDir)) {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+      console.log(`[onboard] Cleaned up temp clone ${tempDir}`);
+    }
+  } catch (e) {
+    console.error(`[onboard] Temp cleanup error: ${e.message}`);
+  }
+};
+
+module.exports = {
+  ensureGithubRepoAccessible,
+  verifyGithubRepoForOnboarding,
+  cloneRepoToTemp,
+  cleanupTempClone,
+};