agentic-workflow-manager 3.7.0 → 3.8.0

package/dist/src/commands/context-budget/budget.js

@@ -0,0 +1,112 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIG_FILE = exports.DEFAULT_FILES = void 0;
+exports.estimateTokens = estimateTokens;
+exports.measure = measure;
+exports.readConfig = readConfig;
+exports.writeConfig = writeConfig;
+exports.checkBudget = checkBudget;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * The feedforward context budget.
+ *
+ * `AGENTS.md`, `CONSTITUTION.md` and `CLAUDE.md` are injected into EVERY agent session
+ * before a single line of code is read, so their size is a per-session tax paid
+ * forever. They grow because curing a lesson is an append and pruning one is a
+ * judgement call nobody is forced to make.
+ *
+ * Prose does not hold this line. Measured on a real repo, `AGENTS.md` went 73KB → 141KB
+ * across 45 revisions and never shrank once, while `harness-retro` already carried an
+ * explicit "merge and prune, never append raw" rule. Adding a second copy of an ignored
+ * rule has no expected effect, so this measures instead.
+ *
+ * It does NOT forbid growth — it makes growth deliberate. First check pins the current
+ * total; later checks report when the files have grown past it. The ways out are pruning
+ * back under, or raising `maxBytes` in a committed diff a human reviews.
+ *
+ * **Where this runs matters as much as what it measures.** It belongs at the last moment
+ * a human is guaranteed to be present — the pre-handoff gate at the end of
+ * `writing-plans`, before execution is handed to subagents. Wired into `awm sensors run`
+ * instead, it would fire during unattended overnight runs and strand the very PR the
+ * user came back expecting. Hence a command, not a sensor.
+ */
+/** Injected into every session by the AWM session hook / context contract. */
+exports.DEFAULT_FILES = ['AGENTS.md', 'CONSTITUTION.md', 'CLAUDE.md'];
+exports.CONFIG_FILE = path_1.default.join('.awm', 'context-budget.json');
+/** Rough but stable: ~4 bytes per token for prose. Reporting only — never a gate input. */
+function estimateTokens(bytes) {
+    return Math.round(bytes / 4 / 1000);
+}
+function measure(cwd, files) {
+    const breakdown = [];
+    let total = 0;
+    for (const f of files) {
+        let s;
+        try {
+            s = fs_1.default.statSync(path_1.default.join(cwd, f));
+        }
+        catch {
+            continue; // a repo need not have all three
+        }
+        if (!s.isFile())
+            continue;
+        total += s.size;
+        breakdown.push({ file: f, bytes: s.size });
+    }
+    return { total, breakdown };
+}
+/**
+ * Read the pinned budget. A malformed or partial config returns null so the caller
+ * re-pins rather than treating an unreadable budget as an absent limit — the quiet
+ * direction of wrong, where the check silently stops checking.
+ */
+function readConfig(cwd) {
+    try {
+        const raw = JSON.parse(fs_1.default.readFileSync(path_1.default.join(cwd, exports.CONFIG_FILE), 'utf-8'));
+        if (typeof raw.maxBytes !== 'number' || !Number.isFinite(raw.maxBytes))
+            return null;
+        return {
+            files: Array.isArray(raw.files) && raw.files.length ? raw.files : exports.DEFAULT_FILES,
+            maxBytes: raw.maxBytes,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function writeConfig(cwd, config) {
+    fs_1.default.mkdirSync(path_1.default.join(cwd, '.awm'), { recursive: true });
+    const body = {
+        _comment: 'Context budget for files injected into every agent session. Raising maxBytes '
+            + 'is allowed but must be a deliberate, reviewed change — see writing-plans, '
+            + 'Context Budget Gate.',
+        ...config,
+    };
+    fs_1.default.writeFileSync(path_1.default.join(cwd, exports.CONFIG_FILE), JSON.stringify(body, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Measure the injected context against the pinned budget.
+ *
+ * On the first check there is nothing to compare against, so the current total is
+ * pinned and the result is `pinned`. Pinning rather than failing means adopting this
+ * never blocks a repo that is already large — it only stops it getting larger.
+ */
+function checkBudget(cwd) {
+    const config = readConfig(cwd);
+    if (!config) {
+        const { total, breakdown } = measure(cwd, exports.DEFAULT_FILES);
+        writeConfig(cwd, { files: exports.DEFAULT_FILES, maxBytes: total });
+        return { status: 'pinned', totalBytes: total, maxBytes: total, breakdown };
+    }
+    const { total, breakdown } = measure(cwd, config.files);
+    return {
+        status: total > config.maxBytes ? 'over' : 'within',
+        totalBytes: total,
+        maxBytes: config.maxBytes,
+        breakdown,
+    };
+}

package/dist/src/commands/context-budget/index.js

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exitCodeFor = exitCodeFor;
+exports.formatReport = formatReport;
+exports.registerContextBudgetCommand = registerContextBudgetCommand;
+const picocolors_1 = __importDefault(require("picocolors"));
+const budget_1 = require("./budget");
+const KB = (bytes) => `${(bytes / 1024).toFixed(0)}KB`;
+/**
+ * Exit code. `over` exits 1 so a caller that wants a hard gate can have one — but the
+ * skill that invokes this (writing-plans, Context Budget Gate) deliberately does not
+ * treat it as one. It runs at the last attended moment and presents a choice; blocking
+ * would strand the unattended runs this whole design exists to protect.
+ */
+function exitCodeFor(report) {
+    return report.status === 'over' ? 1 : 0;
+}
+function formatReport(report) {
+    const tokens = `~${(0, budget_1.estimateTokens)(report.totalBytes)}k tokens`;
+    const breakdown = report.breakdown.map(b => `${b.file} ${KB(b.bytes)}`).join(', ');
+    if (report.status === 'pinned') {
+        return `${picocolors_1.default.green('✔')}  Context budget pinned at ${KB(report.totalBytes)} (${tokens} per session).\n`
+            + `   ${breakdown}\n`
+            + `   Saved to ${budget_1.CONFIG_FILE} — commit it. Growth past this point will report here.\n`;
+    }
+    if (report.status === 'within') {
+        return `${picocolors_1.default.green('✔')}  Context budget OK: ${KB(report.totalBytes)} of ${KB(report.maxBytes)} (${tokens} per session).\n`
+            + `   ${breakdown}\n`;
+    }
+    const over = report.totalBytes - report.maxBytes;
+    return `${picocolors_1.default.yellow('⚠')}  Context budget exceeded: ${KB(report.totalBytes)} vs ${KB(report.maxBytes)} `
+        + `(over by ${KB(over)}).\n`
+        + `   ${breakdown}\n`
+        + `   These files are injected into EVERY session — ${tokens} spent before any code is read.\n\n`
+        + `   Decide now, while you are here:\n`
+        + `     1. Prune  — cheapest moment: that context is already loaded and you are\n`
+        + `                 choosing what matters for the work about to start.\n`
+        + `     2. Raise  — edit "maxBytes" in ${budget_1.CONFIG_FILE}; a reviewed decision to keep\n`
+        + `                 paying for this in every future session.\n`
+        + `     3. Accept — proceed and note it in the plan.\n`;
+}
+function registerContextBudgetCommand(program) {
+    program
+        .command('context-budget')
+        .description('check the size of the files injected into every agent session')
+        .option('--json', 'emit the report as JSON')
+        .option('--cwd <path>', 'directory to measure (default: current)')
+        .action((opts) => {
+        const report = (0, budget_1.checkBudget)(opts.cwd ?? process.cwd());
+        process.stdout.write(opts.json ? JSON.stringify(report, null, 2) + '\n' : formatReport(report));
+        const code = exitCodeFor(report);
+        if (code !== 0)
+            process.exit(code);
+    });
+}

package/dist/src/index.js

@@ -26,6 +26,7 @@ const miro_1 = require("./core/miro");
 const hooks_1 = require("./commands/hooks");
 const sensors_1 = require("./commands/sensors");
 const ledger_1 = require("./commands/ledger");
+const context_budget_1 = require("./commands/context-budget");
 const doctor_1 = require("./commands/doctor");
 const backup_1 = require("./commands/backup");
 const init_1 = require("./commands/init");
@@ -606,6 +607,7 @@ miroCmd.command('sync <storyMapPath>')
 (0, hooks_1.registerHooksCommand)(program);
 (0, sensors_1.registerSensorsCommand)(program);
 (0, ledger_1.registerLedgerCommand)(program);
+(0, context_budget_1.registerContextBudgetCommand)(program);
 (0, doctor_1.registerDoctorCommand)(program);
 (0, backup_1.registerBackupCommand)(program);
 (0, init_1.registerInitCommand)(program);

package/dist/tests/commands/context-budget/budget.test.js

@@ -0,0 +1,100 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const budget_1 = require("../../../src/commands/context-budget/budget");
+const context_budget_1 = require("../../../src/commands/context-budget");
+function project(files) {
+    // CLAUDE.md: no test may reach the real ~/.awm. Everything here is a tmpdir.
+    const dir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-budget-'));
+    for (const [name, bytes] of Object.entries(files)) {
+        fs_1.default.writeFileSync(path_1.default.join(dir, name), 'a'.repeat(bytes));
+    }
+    return dir;
+}
+describe('checkBudget', () => {
+    const dirs = [];
+    const make = (f) => { const d = project(f); dirs.push(d); return d; };
+    afterAll(() => dirs.forEach(d => fs_1.default.rmSync(d, { recursive: true, force: true })));
+    it('pins the current total on the first check instead of failing', () => {
+        // Adopting this must never block a repo that is already large — it only stops
+        // it getting larger. A first-run failure would make it unadoptable exactly
+        // where it is most needed.
+        const dir = make({ 'AGENTS.md': 5000, 'CONSTITUTION.md': 3000 });
+        const report = (0, budget_1.checkBudget)(dir);
+        expect(report.status).toBe('pinned');
+        expect(report.totalBytes).toBe(8000);
+        expect((0, budget_1.readConfig)(dir).maxBytes).toBe(8000);
+    });
+    it('reports over once the files grow past the pin', () => {
+        const dir = make({ 'AGENTS.md': 5000 });
+        (0, budget_1.checkBudget)(dir); // pin at 5000
+        fs_1.default.appendFileSync(path_1.default.join(dir, 'AGENTS.md'), 'b'.repeat(2000));
+        const report = (0, budget_1.checkBudget)(dir);
+        expect(report.status).toBe('over');
+        expect(report.totalBytes).toBe(7000);
+        expect(report.maxBytes).toBe(5000);
+    });
+    it('goes quiet again once pruned back under budget', () => {
+        const dir = make({ 'AGENTS.md': 5000 });
+        (0, budget_1.checkBudget)(dir);
+        fs_1.default.writeFileSync(path_1.default.join(dir, 'AGENTS.md'), 'a'.repeat(4000));
+        expect((0, budget_1.checkBudget)(dir).status).toBe('within');
+    });
+    it('does not re-pin on later checks, so the budget is a real ratchet', () => {
+        // If a later check re-pinned, growth would always look like the new normal and
+        // the budget would never mean anything.
+        const dir = make({ 'AGENTS.md': 5000 });
+        (0, budget_1.checkBudget)(dir);
+        fs_1.default.appendFileSync(path_1.default.join(dir, 'AGENTS.md'), 'b'.repeat(9000));
+        (0, budget_1.checkBudget)(dir);
+        expect((0, budget_1.readConfig)(dir).maxBytes).toBe(5000);
+    });
+    it('counts only the files that exist', () => {
+        const dir = make({ 'AGENTS.md': 1000 }); // no CONSTITUTION.md, no CLAUDE.md
+        const report = (0, budget_1.checkBudget)(dir);
+        expect(report.totalBytes).toBe(1000);
+        expect(report.breakdown.map(b => b.file)).toEqual(['AGENTS.md']);
+    });
+    it('re-pins when the config is unreadable rather than treating it as no limit', () => {
+        // An unparseable budget must not silently disable the check — that is the quiet
+        // direction of wrong, where it stops checking and still reports success.
+        const dir = make({ 'AGENTS.md': 2000 });
+        fs_1.default.mkdirSync(path_1.default.join(dir, '.awm'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(dir, budget_1.CONFIG_FILE), '{ not json');
+        const report = (0, budget_1.checkBudget)(dir);
+        expect(report.status).toBe('pinned');
+        expect((0, budget_1.readConfig)(dir).maxBytes).toBe(2000);
+    });
+    it('honours a custom file list from the config', () => {
+        const dir = make({ 'AGENTS.md': 1000, 'OTHER.md': 500 });
+        fs_1.default.mkdirSync(path_1.default.join(dir, '.awm'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(dir, budget_1.CONFIG_FILE), JSON.stringify({ files: ['OTHER.md'], maxBytes: 100 }));
+        const report = (0, budget_1.checkBudget)(dir);
+        expect(report.totalBytes).toBe(500);
+        expect(report.status).toBe('over');
+    });
+});
+describe('reporting', () => {
+    it('exits non-zero only when over budget', () => {
+        expect((0, context_budget_1.exitCodeFor)({ status: 'over', totalBytes: 2, maxBytes: 1, breakdown: [] })).toBe(1);
+        expect((0, context_budget_1.exitCodeFor)({ status: 'within', totalBytes: 1, maxBytes: 2, breakdown: [] })).toBe(0);
+        expect((0, context_budget_1.exitCodeFor)({ status: 'pinned', totalBytes: 1, maxBytes: 1, breakdown: [] })).toBe(0);
+    });
+    it('offers the three choices when over, since this runs while a human is present', () => {
+        const out = (0, context_budget_1.formatReport)({
+            status: 'over',
+            totalBytes: 227_000,
+            maxBytes: 224_000,
+            breakdown: [{ file: 'AGENTS.md', bytes: 145_000 }],
+        });
+        expect(out).toContain('Prune');
+        expect(out).toContain('Raise');
+        expect(out).toContain('Accept');
+        expect(out).toMatch(/~5[0-9]k tokens/);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-workflow-manager",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "main": "dist/src/index.js",
   "bin": {
     "awm": "./dist/src/index.js"