@mndrk/agx 1.4.64 → 2.0.0-next.0

package/lib/storage/checkpoints.js

@@ -0,0 +1,222 @@
+/**
+ * Checkpoint durability helpers for agx task state.
+ *
+ * Stores checkpoint metadata in checkpoints.json and git patches in patches/*.diff.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { projectRoot, validateSlug } = require('./paths');
+const { ensureDir, fileExists, writeJsonAtomic, writeFileAtomic, readJsonSafe } = require('./atomic');
+
+const MAX_HISTORY = 50;
+const DEFAULT_CHECKPOINTS = { head: null, history: [] };
+const MAX_PLAN_STEPS = 20;
+const MAX_CRITERIA = 10;
+const MAX_CONSTRAINTS = 10;
+const MAX_DONT_REPEAT = 10;
+const CROCKFORD_BASE32 = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+
+let generateUlid = null;
+try {
+    ({ ulid: generateUlid } = require('ulid'));
+} catch {
+    // Offline fallback keeps checkpoint creation functional if dependency install is unavailable.
+    generateUlid = function fallbackUlid() {
+        let time = Date.now();
+        let timePart = '';
+        for (let i = 0; i < 10; i += 1) {
+            timePart = CROCKFORD_BASE32[time % 32] + timePart;
+            time = Math.floor(time / 32);
+        }
+
+        let randomPart = '';
+        const randomBytes = crypto.randomBytes(16);
+        for (let i = 0; i < randomBytes.length; i += 1) {
+            randomPart += CROCKFORD_BASE32[randomBytes[i] & 31];
+        }
+
+        return `${timePart}${randomPart}`;
+    };
+}
+
+function checkpointsTaskRoot(projectSlug, taskSlug) {
+    const projectValidation = validateSlug(projectSlug);
+    if (!projectValidation.valid) {
+        throw new Error(`Invalid project slug: ${projectValidation.error} (got ${typeof projectSlug}: ${JSON.stringify(projectSlug)})`);
+    }
+    const taskValidation = validateSlug(taskSlug);
+    if (!taskValidation.valid) {
+        throw new Error(`Invalid task slug: ${taskValidation.error} (got ${typeof taskSlug}: ${JSON.stringify(taskSlug)})`);
+    }
+
+    return path.join(projectRoot(projectSlug), 'tasks', taskSlug);
+}
+
+function checkpointsPath(projectSlug, taskSlug) {
+    return path.join(checkpointsTaskRoot(projectSlug, taskSlug), 'checkpoints.json');
+}
+
+function normalizeCheckpointsData(data) {
+    if (!data || typeof data !== 'object') {
+        return null;
+    }
+
+    const history = Array.isArray(data.history)
+        ? data.history.filter(entry => entry && typeof entry === 'object')
+        : [];
+    const head = typeof data.head === 'string' ? data.head : null;
+
+    return { head, history };
+}
+
+async function tryReadCheckpoints(filePath) {
+    try {
+        const data = await readJsonSafe(filePath);
+        if (!data) {
+            return null;
+        }
+        return normalizeCheckpointsData(data);
+    } catch {
+        return null;
+    }
+}
+
+async function writeCheckpointsFile(projectSlug, taskSlug, data) {
+    const mainPath = checkpointsPath(projectSlug, taskSlug);
+    const backupPath = `${mainPath}.bak`;
+    const normalized = normalizeCheckpointsData(data) || DEFAULT_CHECKPOINTS;
+
+    await ensureDir(path.dirname(mainPath));
+
+    if (await fileExists(mainPath)) {
+        try {
+            await fs.promises.unlink(backupPath);
+        } catch (err) {
+            if (err.code !== 'ENOENT') {
+                throw err;
+            }
+        }
+
+        await fs.promises.rename(mainPath, backupPath);
+    }
+
+    try {
+        await writeJsonAtomic(mainPath, normalized);
+    } catch (err) {
+        if (!(await fileExists(mainPath)) && (await fileExists(backupPath))) {
+            try {
+                await fs.promises.rename(backupPath, mainPath);
+            } catch {
+                // If restoration fails, keep original write error.
+            }
+        }
+        throw err;
+    }
+
+    return normalized;
+}
+
+async function readCheckpointsFile(projectSlug, taskSlug) {
+    const mainPath = checkpointsPath(projectSlug, taskSlug);
+    const backupPath = `${mainPath}.bak`;
+
+    const mainData = await tryReadCheckpoints(mainPath);
+    if (mainData) {
+        return mainData;
+    }
+
+    const backupData = await tryReadCheckpoints(backupPath);
+    if (backupData) {
+        return backupData;
+    }
+
+    return { ...DEFAULT_CHECKPOINTS };
+}
+
+function patchesDirPath(projectSlug, taskSlug) {
+    return path.join(checkpointsTaskRoot(projectSlug, taskSlug), 'patches');
+}
+
+function patchFileRelativePath(checkpointId) {
+    return `patches/${checkpointId}.diff`;
+}
+
+async function createCheckpoint(projectSlug, taskSlug, data = {}) {
+    const current = await readCheckpointsFile(projectSlug, taskSlug);
+
+    const id = `cp_${generateUlid()}`;
+    const createdAt = new Date().toISOString();
+
+    const inputGit = data && typeof data.git === 'object' && data.git !== null
+        ? data.git
+        : {};
+    const gitPatch = typeof inputGit.patch === 'string' ? inputGit.patch : null;
+    let patchFile = null;
+
+    if (gitPatch !== null) {
+        patchFile = patchFileRelativePath(id);
+        const patchDir = patchesDirPath(projectSlug, taskSlug);
+        await ensureDir(patchDir);
+        await writeFileAtomic(path.join(checkpointsTaskRoot(projectSlug, taskSlug), patchFile), gitPatch);
+    }
+
+    const git = {
+        ...inputGit,
+    };
+    if (patchFile) {
+        git.patchFile = patchFile;
+    }
+    delete git.patch;
+
+    // Apply limits to prevent unbounded growth
+    const limitArray = (arr, max) => Array.isArray(arr) ? arr.slice(0, max) : arr;
+    
+    const limitedData = { ...data };
+    if (limitedData.plan && Array.isArray(limitedData.plan.steps)) {
+        limitedData.plan = { ...limitedData.plan, steps: limitArray(limitedData.plan.steps, MAX_PLAN_STEPS) };
+    }
+    if (Array.isArray(limitedData.criteria)) {
+        limitedData.criteria = limitArray(limitedData.criteria, MAX_CRITERIA);
+    }
+    if (Array.isArray(limitedData.constraints)) {
+        limitedData.constraints = limitArray(limitedData.constraints, MAX_CONSTRAINTS);
+    }
+    if (Array.isArray(limitedData.dontRepeat)) {
+        limitedData.dontRepeat = limitArray(limitedData.dontRepeat, MAX_DONT_REPEAT);
+    }
+
+    const checkpoint = {
+        ...limitedData,
+        id,
+        createdAt,
+        git,
+    };
+
+    const history = [checkpoint, ...current.history].slice(0, MAX_HISTORY);
+    const next = {
+        head: id,
+        history,
+    };
+
+    await writeCheckpointsFile(projectSlug, taskSlug, next);
+    return checkpoint;
+}
+
+async function getHead(projectSlug, taskSlug) {
+    const data = await readCheckpointsFile(projectSlug, taskSlug);
+    if (!data.head) {
+        return null;
+    }
+    return data.history.find(cp => cp && cp.id === data.head) || null;
+}
+
+module.exports = {
+    MAX_HISTORY,
+    checkpointsPath,
+    writeCheckpointsFile,
+    readCheckpointsFile,
+    createCheckpoint,
+    getHead,
+};

package/lib/storage/git.js

@@ -0,0 +1,147 @@
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const EXEC_OPTIONS = { encoding: 'utf8', maxBuffer: 10 * 1024 * 1024 };
+const MAX_CHANGED_FILES = 20;
+
+function runGitCommand(args, cwd, overrideOptions = {}) {
+    const command = ['git', ...args].join(' ');
+    try {
+        return execSync(command, { ...EXEC_OPTIONS, cwd, ...overrideOptions });
+    } catch (err) {
+        const message = `${command} failed${err.message ? `: ${err.message}` : ''}`;
+        const wrapped = new Error(message);
+        wrapped.cause = err;
+        throw wrapped;
+    }
+}
+
+function parseChangedFiles(statusOutput) {
+    if (!statusOutput) return [];
+    const seen = new Set();
+    const result = [];
+    const lines = statusOutput.split(/\r?\n/);
+    for (const rawLine of lines) {
+        if (!rawLine) continue;
+        const trimmed = rawLine.trim();
+        if (!trimmed || trimmed.length < 4) continue;
+        let filePath = trimmed.slice(3).trim();
+        const arrowIndex = filePath.indexOf('->');
+        if (arrowIndex >= 0) {
+            filePath = filePath.slice(arrowIndex + 2).trim();
+        }
+        if (!filePath || seen.has(filePath)) continue;
+        seen.add(filePath);
+        result.push(filePath);
+        if (result.length >= MAX_CHANGED_FILES) break;
+    }
+    return result;
+}
+
+function captureGitState(cwd) {
+    if (!cwd) {
+        throw new Error('captureGitState requires a working directory');
+    }
+
+    const statusOutput = runGitCommand(['status', '--porcelain'], cwd);
+    const trimmedStatus = statusOutput.trim();
+
+    const state = {
+        sha: runGitCommand(['rev-parse', 'HEAD'], cwd).trim(),
+        branch: null,
+        dirty: trimmedStatus.length > 0,
+        patch: null,
+        changedFiles: parseChangedFiles(statusOutput),
+    };
+
+    const branchName = runGitCommand(['rev-parse', '--abbrev-ref', 'HEAD'], cwd).trim();
+    state.branch = branchName === 'HEAD' ? null : branchName;
+
+    if (state.dirty) {
+        const diff = runGitCommand(['diff', 'HEAD'], cwd);
+        state.patch = diff ? diff : null;
+    }
+
+    return state;
+}
+
+function resolvePatchFile(patchFile, cwd) {
+    if (!patchFile || typeof patchFile !== 'string') {
+        return null;
+    }
+
+    const candidates = [];
+    candidates.push(patchFile);
+    if (!path.isAbsolute(patchFile)) {
+        candidates.push(path.resolve(cwd, patchFile));
+        if (cwd !== process.cwd()) {
+            candidates.push(path.resolve(process.cwd(), patchFile));
+        }
+    }
+
+    for (const candidate of candidates) {
+        try {
+            if (fs.existsSync(candidate)) {
+                return candidate;
+            }
+        } catch {
+            // ignore
+        }
+    }
+
+    return null;
+}
+
+function readPatch(patchFilePath) {
+    if (!patchFilePath) return null;
+    try {
+        const contents = fs.readFileSync(patchFilePath, 'utf8');
+        return contents.trim() ? contents : null;
+    } catch (err) {
+        throw new Error(`Unable to read patch file ${patchFilePath}: ${err.message}`);
+    }
+}
+
+function restoreGitState(gitState, cwd, opts = {}) {
+    if (!cwd) {
+        throw new Error('restoreGitState requires a working directory');
+    }
+
+    if (!gitState || typeof gitState !== 'object') {
+        throw new Error('restoreGitState requires a git state object');
+    }
+
+    const { sha, patchFile, patch: inlinePatch } = gitState;
+    if (!sha || typeof sha !== 'string') {
+        throw new Error('restoreGitState requires a saved git sha');
+    }
+
+    const statusOutput = runGitCommand(['status', '--porcelain'], cwd);
+    const hasDirty = Boolean(statusOutput.trim());
+    if (hasDirty && !opts.force) {
+        throw new Error('Working tree has uncommitted changes; pass { force: true } to override');
+    }
+
+    runGitCommand(['reset', '--hard'], cwd);
+
+    if (opts.force) {
+        runGitCommand(['clean', '-fd'], cwd);
+    }
+
+    runGitCommand(['checkout', sha], cwd);
+
+    const resolvedPatchFile = resolvePatchFile(patchFile, cwd);
+    const resolvedPatch = resolvedPatchFile ? readPatch(resolvedPatchFile) : null;
+    const inlineContent = typeof inlinePatch === 'string' && inlinePatch.trim() ? inlinePatch : null;
+    const patchToApply = resolvedPatch || inlineContent;
+
+    if (patchToApply) {
+        runGitCommand(['apply', '--3way'], cwd, { input: patchToApply });
+    }
+}
+
+module.exports = {
+    captureGitState,
+    restoreGitState,
+};

package/lib/storage/graph.js

@@ -0,0 +1,80 @@
+/**
+ * Execution graph serialization helpers for agx local state storage.
+ *
+ * Persists the full v2 execution graph as task-local graph.json.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { graphJsonPath } = require('./paths');
+const { ensureDir, readJsonSafe, writeJsonAtomic } = require('./atomic');
+
+function isObject(value) {
+    return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function validateGraphShape(graph) {
+    if (!isObject(graph)) {
+        throw new Error('graph must be an object');
+    }
+    if (typeof graph.id !== 'string' || !graph.id.trim()) {
+        throw new Error('graph.id is required');
+    }
+    if (typeof graph.taskId !== 'string' || !graph.taskId.trim()) {
+        throw new Error('graph.taskId is required');
+    }
+    if (!isObject(graph.nodes)) {
+        throw new Error('graph.nodes must be an object');
+    }
+    if (!Array.isArray(graph.edges)) {
+        throw new Error('graph.edges must be an array');
+    }
+}
+
+/**
+ * Read a task execution graph.
+ * @param {string} projectSlug
+ * @param {string} taskSlug
+ * @returns {Promise<object|null>}
+ */
+async function readTaskGraph(projectSlug, taskSlug) {
+    return readJsonSafe(graphJsonPath(projectSlug, taskSlug));
+}
+
+/**
+ * Write a task execution graph.
+ * @param {string} projectSlug
+ * @param {string} taskSlug
+ * @param {object} graph
+ * @returns {Promise<object>}
+ */
+async function writeTaskGraph(projectSlug, taskSlug, graph) {
+    validateGraphShape(graph);
+    const filePath = graphJsonPath(projectSlug, taskSlug);
+    await ensureDir(path.dirname(filePath));
+    await writeJsonAtomic(filePath, graph);
+    return graph;
+}
+
+/**
+ * Delete a task execution graph file if present.
+ * @param {string} projectSlug
+ * @param {string} taskSlug
+ * @returns {Promise<void>}
+ */
+async function deleteTaskGraph(projectSlug, taskSlug) {
+    const filePath = graphJsonPath(projectSlug, taskSlug);
+    try {
+        await fs.promises.unlink(filePath);
+    } catch (err) {
+        if (err.code !== 'ENOENT') {
+            throw err;
+        }
+    }
+}
+
+module.exports = {
+    readTaskGraph,
+    writeTaskGraph,
+    deleteTaskGraph,
+};

package/lib/storage/index.js

@@ -11,7 +11,10 @@ const locks = require('./locks');
 const events = require('./events');
 const state = require('./state');
 const runs = require('./runs');
+const checkpoints = require('./checkpoints');
 const promptBuilder = require('./prompt_builder');
+const git = require('./git');
+const graph = require('./graph');
 
 module.exports = {
     // Paths
@@ -32,6 +35,12 @@ module.exports = {
     // Runs
     ...runs,
 
+    // Checkpoints
+    ...checkpoints,
+
+    // Graph serialization
+    ...graph,
+
     // Prompt builder
     ...promptBuilder,
 
@@ -42,5 +51,8 @@ module.exports = {
     events,
     state,
     runs,
+    checkpoints,
+    graph,
     promptBuilder,
+    git,
 };

package/lib/storage/paths.js

@@ -296,6 +296,16 @@ function lastRunPath(projectSlug, taskSlug) {
     return path.join(taskRoot(projectSlug, taskSlug), 'last_run.json');
 }
 
+/**
+ * Get the graph.json path for a task.
+ * @param {string} projectSlug
+ * @param {string} taskSlug
+ * @returns {string}
+ */
+function graphJsonPath(projectSlug, taskSlug) {
+    return path.join(taskRoot(projectSlug, taskSlug), 'graph.json');
+}
+
 /**
  * Get the .lock path for a task.
  * @param {string} projectSlug
@@ -425,6 +435,7 @@ module.exports = {
     workingSetPath,
     approvalsPath,
     lastRunPath,
+    graphJsonPath,
     taskLockPath,
     runRoot,
     runRootLegacy,

package/lib/storage/state.js

@@ -515,6 +515,8 @@ async function approveRequest(projectSlug, taskSlug, approvalId) {
     const [request] = approvals.pending.splice(idx, 1);
     approvals.approved.push(request);
     await writeApprovals(projectSlug, taskSlug, approvals);
+    // Local task lifecycle uses "pending" as the queued/runnable state.
+    await updateTaskState(projectSlug, taskSlug, { status: 'pending' });
 
     await appendEventToLastRun(projectSlug, taskSlug, approvalGrantedEvent({ id: request.id }));