@colin4k1024/tsp 2.5.3 → 2.5.4

package/scripts/lib/heartbeat-scheduler.js

@@ -14,9 +14,11 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
-const yaml = require ? undefined : undefined; // yaml parsing fallback below
+const yaml = require('js-yaml');
 
 const { createGoal, saveGoal } = require('./completion-oracle');
+const loopStateStore = require('./loop-state-store');
+const { parseLoopSpecContent } = require('./loop-spec');
 
 const DEFAULT_CONFIG = {
   interval: '30m',
@@ -75,12 +77,40 @@ function parseSimpleYaml(content) {
 }
 
 function loadConfig(projectRoot) {
-  const configPath = path.join(projectRoot || process.cwd(), '.claude', 'heartbeat.yaml');
-  if (!fs.existsSync(configPath)) return DEFAULT_CONFIG;
+  const root = projectRoot || process.cwd();
+  const loopSpecPath = path.join(root, '.tsp', 'loop.yaml');
+  if (fs.existsSync(loopSpecPath)) {
+    try {
+      const loopSpec = parseLoopSpecContent(fs.readFileSync(loopSpecPath, 'utf-8'), loopSpecPath);
+      return {
+        ...DEFAULT_CONFIG,
+        interval: loopSpec.cadence,
+        scans: loopSpec.gates.map(gate => ({
+          name: gate.name,
+          command: `${gate.command} 2>&1; echo EXIT:$?`,
+          onFailure: SCAN_ACTIONS.autoGoal,
+          description: gate.description || gate.name,
+        })),
+        budget: {
+          ...DEFAULT_CONFIG.budget,
+          maxDollarsPerHour: loopSpec.budget.maxDollars,
+        },
+      };
+    } catch {
+      return DEFAULT_CONFIG;
+    }
+  }
+
+  const configPath = [
+    path.join(root, '.tsp', 'heartbeat.yaml'),
+    path.join(root, '.claude', 'heartbeat.yaml'),
+  ].find(candidate => fs.existsSync(candidate));
+
+  if (!configPath) return DEFAULT_CONFIG;
 
   try {
     const content = fs.readFileSync(configPath, 'utf-8');
-    const parsed = parseSimpleYaml(content);
+    const parsed = yaml.load(content, { schema: yaml.JSON_SCHEMA }) || parseSimpleYaml(content);
     return { ...DEFAULT_CONFIG, ...parsed.heartbeat };
   } catch {
     return DEFAULT_CONFIG;
@@ -147,14 +177,7 @@ function createTriageItem(scan, result) {
 }
 
 function appendToTriageInbox(item) {
-  const home = process.env.HOME || process.env.USERPROFILE || '';
-  const inboxDir = path.join(home, '.claude', 'triage');
-  if (!fs.existsSync(inboxDir)) {
-    fs.mkdirSync(inboxDir, { recursive: true });
-  }
-  const inboxPath = path.join(inboxDir, 'inbox.jsonl');
-  fs.appendFileSync(inboxPath, JSON.stringify(item) + '\n', 'utf-8');
-  return inboxPath;
+  return loopStateStore.appendTriageItem(item);
 }
 
 function createGoalFromScanFailure(scan, result) {
@@ -181,7 +204,7 @@ function runHeartbeat(projectRoot) {
   if (config.scans.length === 0) {
     return {
       status: 'no_scans',
-      message: 'No scans configured in .claude/heartbeat.yaml',
+      message: 'No scans configured in .tsp/loop.yaml, .tsp/heartbeat.yaml, or .claude/heartbeat.yaml',
       results: [],
     };
   }
@@ -216,14 +239,10 @@ function runHeartbeat(projectRoot) {
 function getHeartbeatStatus(projectRoot) {
   const config = loadConfig(projectRoot);
 
-  const home = process.env.HOME || process.env.USERPROFILE || '';
-  const lastRunPath = path.join(home, '.claude', 'heartbeat-last-run.json');
   let lastRun = null;
-  if (fs.existsSync(lastRunPath)) {
-    try {
-      lastRun = JSON.parse(fs.readFileSync(lastRunPath, 'utf-8'));
-    } catch { /* ignore */ }
-  }
+  try {
+    lastRun = loopStateStore.loadHeartbeat('last-run');
+  } catch { /* ignore */ }
 
   return {
     configured: config.scans.length > 0,
@@ -236,11 +255,7 @@ function getHeartbeatStatus(projectRoot) {
 }
 
 function saveLastRun(result) {
-  const home = process.env.HOME || process.env.USERPROFILE || '';
-  const lastRunPath = path.join(home, '.claude', 'heartbeat-last-run.json');
-  const dir = path.dirname(lastRunPath);
-  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(lastRunPath, JSON.stringify(result, null, 2), 'utf-8');
+  return loopStateStore.saveHeartbeat('last-run', result);
 }
 
 function parseInterval(interval) {

package/scripts/lib/install-targets/registry.js

@@ -11,7 +11,7 @@ const geminiProject = require('./gemini-project');
 const opencodeHome = require('./opencode-home');
 const windsurfProject = require('./windsurf-project');
 
-const PUBLIC_INSTALL_TARGETS = Object.freeze(['claude', 'codex', 'opencode', 'cangming', 'codewhale']);
+const PUBLIC_INSTALL_TARGETS = Object.freeze(['claude', 'codex', 'opencode']);
 const TARGET_ALIASES = Object.freeze({
   'claude-code': 'claude',
   claudecode: 'claude',

package/scripts/lib/loop-oracle.js

@@ -0,0 +1,5 @@
+'use strict';
+
+// Compatibility layer for the loop-engineering runtime. The existing goal
+// oracle remains the implementation while callers migrate to loop naming.
+module.exports = require('./completion-oracle');

package/scripts/lib/loop-spec.js

@@ -0,0 +1,168 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+class LoopSpecError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = 'LoopSpecError';
+    this.details = details;
+    this.code = details.code || 'loop_spec_error';
+  }
+}
+
+function ensureObject(value, label, filePath) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new LoopSpecError(`${label} must be an object`, {
+      filePath,
+      code: 'invalid_payload',
+    });
+  }
+}
+
+function ensureNonEmptyString(value, label, filePath) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new LoopSpecError(`${label} must be a non-empty string`, {
+      filePath,
+      code: 'invalid_field',
+    });
+  }
+}
+
+function ensurePositiveNumber(value, label, filePath) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+    throw new LoopSpecError(`${label} must be a positive number`, {
+      filePath,
+      code: 'invalid_budget',
+    });
+  }
+}
+
+function normalizeGate(gate, index, filePath) {
+  ensureObject(gate, `loop.gates[${index}]`, filePath);
+  ensureNonEmptyString(gate.name, `loop.gates[${index}].name`, filePath);
+  ensureNonEmptyString(gate.command, `loop.gates[${index}].command`, filePath);
+
+  return {
+    name: gate.name.trim(),
+    command: gate.command.trim(),
+    description: typeof gate.description === 'string' && gate.description.trim()
+      ? gate.description.trim()
+      : null,
+  };
+}
+
+function normalizeBudget(budget, filePath) {
+  ensureObject(budget, 'loop.budget', filePath);
+  ensurePositiveNumber(budget.maxIterations, 'loop.budget.maxIterations', filePath);
+  ensurePositiveNumber(budget.maxDollars, 'loop.budget.maxDollars', filePath);
+  ensureNonEmptyString(budget.maxDuration, 'loop.budget.maxDuration', filePath);
+
+  if (!/^(\d+)(m|h)$/.test(budget.maxDuration)) {
+    throw new LoopSpecError('loop.budget.maxDuration must use Nm or Nh format', {
+      filePath,
+      code: 'invalid_budget_duration',
+    });
+  }
+
+  return {
+    maxIterations: budget.maxIterations,
+    maxDuration: budget.maxDuration,
+    maxDollars: budget.maxDollars,
+  };
+}
+
+function normalizeActor(actor, label, filePath) {
+  ensureObject(actor, label, filePath);
+  ensureNonEmptyString(actor.role, `${label}.role`, filePath);
+
+  return {
+    role: actor.role.trim(),
+    writeAccess: actor.writeAccess === true,
+  };
+}
+
+function normalizeLoopSpec(payload, filePath = '<inline>') {
+  ensureObject(payload, 'loop spec', filePath);
+  ensureObject(payload.loop, 'loop', filePath);
+
+  const loop = payload.loop;
+  ensureNonEmptyString(loop.id, 'loop.id', filePath);
+  ensureNonEmptyString(loop.description, 'loop.description', filePath);
+  ensureNonEmptyString(loop.cadence, 'loop.cadence', filePath);
+  ensureNonEmptyString(loop.skill, 'loop.skill', filePath);
+  ensureNonEmptyString(loop.stateFile, 'loop.stateFile', filePath);
+
+  if (!/^(\d+)(m|h|d)$/.test(loop.cadence)) {
+    throw new LoopSpecError('loop.cadence must use Nm, Nh, or Nd format', {
+      filePath,
+      code: 'invalid_cadence',
+    });
+  }
+
+  if (!Array.isArray(loop.gates) || loop.gates.length === 0) {
+    throw new LoopSpecError('loop.gates must include at least one hard verification gate', {
+      filePath,
+      code: 'missing_gates',
+    });
+  }
+
+  return {
+    id: loop.id.trim(),
+    description: loop.description.trim(),
+    cadence: loop.cadence.trim(),
+    skill: loop.skill.trim(),
+    stateFile: loop.stateFile.trim(),
+    gates: loop.gates.map((gate, index) => normalizeGate(gate, index, filePath)),
+    maker: normalizeActor(loop.maker, 'loop.maker', filePath),
+    checker: normalizeActor(loop.checker, 'loop.checker', filePath),
+    budget: normalizeBudget(loop.budget, filePath),
+    escalation: {
+      onBudgetExhausted: loop.escalation?.onBudgetExhausted || 'triage',
+      onSecurityFinding: loop.escalation?.onSecurityFinding || 'human',
+    },
+  };
+}
+
+function parseLoopSpecContent(content, filePath = '<inline>') {
+  let payload;
+  try {
+    payload = yaml.load(content, {
+      filename: path.basename(filePath),
+      schema: yaml.JSON_SCHEMA,
+    });
+  } catch (error) {
+    throw new LoopSpecError(`Failed to parse loop spec YAML: ${error.message}`, {
+      filePath,
+      code: 'yaml_parse_error',
+    });
+  }
+
+  return normalizeLoopSpec(payload, filePath);
+}
+
+function loadLoopSpecFile(filePath) {
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch (error) {
+    throw new LoopSpecError(`Failed to read loop spec file: ${error.message}`, {
+      filePath,
+      code: 'read_error',
+    });
+  }
+
+  return {
+    path: filePath,
+    loop: parseLoopSpecContent(content, filePath),
+  };
+}
+
+module.exports = {
+  LoopSpecError,
+  normalizeLoopSpec,
+  parseLoopSpecContent,
+  loadLoopSpecFile,
+};

package/scripts/lib/loop-state-store.js

@@ -0,0 +1,221 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const DEFAULT_TARGET = 'claude';
+
+const TARGET_STATE_DIRS = Object.freeze({
+  claude: ['.claude', 'loops'],
+  codex: ['.codex', 'loops'],
+  opencode: ['.config', 'opencode', 'loops'],
+  cangming: ['.cangming', 'loops'],
+  codewhale: ['.codewhale', 'loops'],
+  codebuddy: ['.codebuddy', 'loops'],
+});
+
+const LEGACY_CLAUDE_DIRS = Object.freeze({
+  goals: ['.claude', 'goals'],
+  triage: ['.claude', 'triage'],
+  heartbeatLastRun: ['.claude', 'heartbeat-last-run.json'],
+});
+
+function readHome() {
+  return process.env.HOME || process.env.USERPROFILE || os.homedir();
+}
+
+function normalizeTarget(target) {
+  return String(target || process.env.TSP_LOOP_TARGET || DEFAULT_TARGET).trim().toLowerCase() || DEFAULT_TARGET;
+}
+
+function projectLocalStateDir(projectRoot) {
+  if (!projectRoot) return null;
+  return path.join(path.resolve(projectRoot), '.tsp', 'loops');
+}
+
+function targetDefaultStateDir(target) {
+  const home = readHome();
+  const parts = TARGET_STATE_DIRS[normalizeTarget(target)] || TARGET_STATE_DIRS[DEFAULT_TARGET];
+  return path.join(home, ...parts);
+}
+
+function getLoopStateDir(options = {}) {
+  if (process.env.TSP_LOOP_STATE_DIR) {
+    return path.resolve(process.env.TSP_LOOP_STATE_DIR);
+  }
+
+  if (options.stateDir) {
+    return path.resolve(options.stateDir);
+  }
+
+  if (options.projectRoot) {
+    return projectLocalStateDir(options.projectRoot);
+  }
+
+  return targetDefaultStateDir(options.target);
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+  return dirPath;
+}
+
+function ensureLoopStateDir(options = {}) {
+  return ensureDir(getLoopStateDir(options));
+}
+
+function getNamespaceDir(namespace, options = {}) {
+  return path.join(getLoopStateDir(options), namespace);
+}
+
+function ensureNamespaceDir(namespace, options = {}) {
+  return ensureDir(getNamespaceDir(namespace, options));
+}
+
+function getGoalPath(goalId, options = {}) {
+  return path.join(getNamespaceDir('goals', options), `${goalId}.json`);
+}
+
+function getTriageInboxPath(options = {}) {
+  return path.join(getNamespaceDir('triage', options), 'inbox.jsonl');
+}
+
+function getHeartbeatPath(loopId = 'default', options = {}) {
+  return path.join(getNamespaceDir('heartbeat', options), `${loopId}.json`);
+}
+
+function getLoopMarkdownStatePath(loopId, options = {}) {
+  return path.join(getNamespaceDir('state', options), `${loopId}.md`);
+}
+
+function writeJson(filePath, value) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  return filePath;
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function saveGoal(goal, options = {}) {
+  return writeJson(getGoalPath(goal.goalId, options), goal);
+}
+
+function loadGoal(goalId, options = {}) {
+  const filePath = getGoalPath(goalId, options);
+  if (fs.existsSync(filePath)) {
+    return readJson(filePath);
+  }
+
+  const legacyPath = getLegacyGoalPath(goalId);
+  if (!options.disableLegacyLookup && legacyPath && fs.existsSync(legacyPath)) {
+    return readJson(legacyPath);
+  }
+
+  return null;
+}
+
+function listJsonFiles(dirPath) {
+  if (!fs.existsSync(dirPath)) return [];
+  return fs.readdirSync(dirPath)
+    .filter(fileName => fileName.endsWith('.json'))
+    .map(fileName => path.join(dirPath, fileName));
+}
+
+function listGoals(filter, options = {}) {
+  const filePaths = listJsonFiles(getNamespaceDir('goals', options));
+
+  if (!options.disableLegacyLookup) {
+    const legacyDir = getLegacyDir('goals');
+    if (legacyDir && path.resolve(legacyDir) !== path.resolve(getNamespaceDir('goals', options))) {
+      filePaths.push(...listJsonFiles(legacyDir));
+    }
+  }
+
+  const seenGoalIds = new Set();
+  return filePaths
+    .map(filePath => {
+      try {
+        return readJson(filePath);
+      } catch {
+        return null;
+      }
+    })
+    .filter(goal => {
+      if (!goal || !goal.goalId || seenGoalIds.has(goal.goalId)) return false;
+      seenGoalIds.add(goal.goalId);
+      return true;
+    })
+    .filter(goal => !filter || goal.state === filter)
+    .sort((a, b) => new Date(b.updatedAt || 0) - new Date(a.updatedAt || 0));
+}
+
+function appendTriageItem(item, options = {}) {
+  const inboxPath = getTriageInboxPath(options);
+  ensureDir(path.dirname(inboxPath));
+  fs.appendFileSync(inboxPath, `${JSON.stringify(item)}\n`, 'utf8');
+  return inboxPath;
+}
+
+function saveHeartbeat(loopId, value, options = {}) {
+  return writeJson(getHeartbeatPath(loopId, options), value);
+}
+
+function loadHeartbeat(loopId = 'default', options = {}) {
+  const filePath = getHeartbeatPath(loopId, options);
+  if (fs.existsSync(filePath)) {
+    return readJson(filePath);
+  }
+
+  const legacyPath = getLegacyHeartbeatLastRunPath();
+  if (!options.disableLegacyLookup && loopId === 'last-run' && legacyPath && fs.existsSync(legacyPath)) {
+    return readJson(legacyPath);
+  }
+
+  return null;
+}
+
+function saveLoopMarkdownState(loopId, content, options = {}) {
+  const statePath = getLoopMarkdownStatePath(loopId, options);
+  ensureDir(path.dirname(statePath));
+  fs.writeFileSync(statePath, String(content), 'utf8');
+  return statePath;
+}
+
+function getLegacyDir(namespace) {
+  const parts = LEGACY_CLAUDE_DIRS[namespace];
+  if (!parts) return null;
+  return path.join(readHome(), ...parts);
+}
+
+function getLegacyGoalPath(goalId) {
+  const legacyDir = getLegacyDir('goals');
+  return legacyDir ? path.join(legacyDir, `${goalId}.json`) : null;
+}
+
+function getLegacyHeartbeatLastRunPath() {
+  return path.join(readHome(), ...LEGACY_CLAUDE_DIRS.heartbeatLastRun);
+}
+
+module.exports = {
+  TARGET_STATE_DIRS,
+  getLoopStateDir,
+  ensureLoopStateDir,
+  getNamespaceDir,
+  ensureNamespaceDir,
+  getGoalPath,
+  getTriageInboxPath,
+  getHeartbeatPath,
+  getLoopMarkdownStatePath,
+  saveGoal,
+  loadGoal,
+  listGoals,
+  appendTriageItem,
+  saveHeartbeat,
+  loadHeartbeat,
+  saveLoopMarkdownState,
+  targetDefaultStateDir,
+  projectLocalStateDir,
+};

package/scripts/lib/transcript-usage.js

@@ -54,8 +54,13 @@ function normalizeUsage(raw) {
   const outputTokens = Number(raw.output_tokens || raw.completion_tokens || 0) || 0;
   const cacheCreationTokens = Number(raw.cache_creation_input_tokens || raw.cache_creation_prompt_tokens || 0) || 0;
   const cacheReadTokens = Number(raw.cache_read_input_tokens || raw.cache_read_prompt_tokens || raw.cached_tokens || 0) || 0;
+  const totalTokens = Number(raw.total_tokens || 0) || 0;
 
-  const contextTokens = inputTokens + outputTokens + cacheCreationTokens + cacheReadTokens;
+  // CCometixLine's context-window segment treats active context as prompt-side
+  // tokens: input + cache creation + cache read. The current turn's output is
+  // tracked separately because it becomes prompt-side context on the next turn.
+  const promptSideContextTokens = inputTokens + cacheCreationTokens + cacheReadTokens;
+  const contextTokens = promptSideContextTokens || totalTokens || (inputTokens + outputTokens);
   if (contextTokens === 0) return null;
 
   return {
@@ -63,6 +68,7 @@ function normalizeUsage(raw) {
     outputTokens,
     cacheCreationTokens,
     cacheReadTokens,
+    totalTokens,
     contextTokens,
   };
 }
@@ -163,11 +169,15 @@ function resolveTranscriptMetrics(transcriptPath, modelId) {
 
   const contextLimit = resolveContextLimit(modelId);
   const usagePct = Math.max(0, Math.min(100, Math.round((usage.contextTokens / contextLimit) * 100)));
+  const remainingTokens = Math.max(0, contextLimit - usage.contextTokens);
+  const remainingPct = Math.max(0, Math.min(100, Math.round((remainingTokens / contextLimit) * 100)));
 
   return {
     usagePct,
     contextTokens: usage.contextTokens,
     contextLimit,
+    remainingTokens,
+    remainingPct,
     source: 'transcript_usage',
   };
 }

package/skills/goframe-v2/examples/practices/quick-demo/manifest/config/config.yaml

@@ -1,15 +1,15 @@
-# https://goframe.org/docs/web/server-config-file-template
-server:
-  address:     ":8000"
-  openapiPath: "/api.json"
-  swaggerPath: "/swagger"
-
-# https://goframe.org/docs/core/glog-config
-logger:
-  level : "all"
-  stdout: true
-
-# https://goframe.org/docs/core/gdb-config-file
-database:
-  default:
+# https://goframe.org/docs/web/server-config-file-template
+server:
+  address:     ":8000"
+  openapiPath: "/api.json"
+  swaggerPath: "/swagger"
+
+# https://goframe.org/docs/core/glog-config
+logger:
+  level : "all"
+  stdout: true
+
+# https://goframe.org/docs/core/gdb-config-file
+database:
+  default:
     link: "mysql:root:12345678@tcp(127.0.0.1:3306)/test"