@voxslopuli/openagentsy 0.0.0-stage → 0.2.0

package/dist/report/oversight.js

@@ -0,0 +1,146 @@
+import { access, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { closeDatabase, listRecords, openDatabase, } from '@openagentsy/core';
+import { createWaiverStore, listLessons, pendingLessons } from '@openagentsy/hooks';
+/**
+ * The oversight of the scope.
+ *
+ * The counts are the board's records, the lessons that wait for a person,
+ * the waivers a person recorded, the audit log and the findings store. The
+ * two the plan names and no package keeps are carried as measurements that
+ * are not known, with the reason: a zero there would look like a
+ * measurement, and it is not one.
+ */
+/** How many records one page of the board holds. */
+const PAGE_SIZE = 100;
+/** The bean the archivist posts a candidate memory under. */
+const MEMORY_BEAN = 'memory';
+/** The states a decided candidate carries. */
+const DECIDED_STATES = ['promoted', 'rejected'];
+/**
+ * Every record on the board.
+ *
+ * The board holds more than one page of records, and a report that read
+ * only the first page would undercount a project with a long history. The
+ * pages are walked until one comes back short.
+ */
+async function boardRecords(stateRoot) {
+    const path = join(stateRoot, '.openagentsy', 'board.sqlite');
+    const exists = await access(path).then(() => true, () => false);
+    if (!exists)
+        return [];
+    const db = openDatabase(path);
+    try {
+        const found = [];
+        let cursor = 0;
+        for (;;) {
+            const page = listRecords(db, { cursor, limit: PAGE_SIZE });
+            found.push(...page.records);
+            if (page.records.length < PAGE_SIZE)
+                return found;
+            cursor = page.nextCursor;
+        }
+    }
+    finally {
+        closeDatabase(db);
+    }
+}
+/**
+ * The memory candidates waiting for a person.
+ *
+ * A candidate is a board record under the memory bean that no person has
+ * decided on, and the decided states are the ones the memory package
+ * writes: promoted and rejected. The rule is the memory package's, and the
+ * report counts the records itself because the package sits above the
+ * adapter and the report needs nothing else of it.
+ */
+function memoryCandidates(records) {
+    return records.filter((record) => record.bean === MEMORY_BEAN && !DECIDED_STATES.includes(record.state)).length;
+}
+/** The lines of the audit log. */
+async function auditEntries(stateRoot) {
+    const path = join(stateRoot, '.openagentsy', 'audit.jsonl');
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch {
+        return 0;
+    }
+    return text.split('\n').filter((line) => line.trim() !== '').length;
+}
+/**
+ * The findings of the scope.
+ *
+ * The findings are the store's, read through the quality package's read
+ * path. A bean scope reads the findings of that task, because the ledger
+ * reads the task of a bean the same way. Every other scope reads them all:
+ * the findings store has no session and no window, and a report that
+ * narrowed it by guesswork would be narrowing it wrongly.
+ */
+export function scopedFindings(findings, scope) {
+    const scoped = [];
+    for (const [taskId, entries] of Object.entries(findings)) {
+        if (scope.kind === 'bean' && taskId !== scope.id)
+            continue;
+        scoped.push(...entries);
+    }
+    return scoped;
+}
+/**
+ * The open floor findings of the scope.
+ *
+ * The floor tier is the one the gate refuses a ship over, so a report that
+ * counts the open floor findings is counting the things that would stop the
+ * work from shipping.
+ */
+function openFloor(findings, scope) {
+    const found = [];
+    for (const [taskId, entries] of Object.entries(findings)) {
+        if (scope.kind === 'bean' && taskId !== scope.id)
+            continue;
+        for (const finding of entries) {
+            if (finding.tier !== 'floor')
+                continue;
+            found.push({
+                taskId,
+                ruleId: finding.ruleId,
+                file: finding.file,
+                message: finding.message,
+            });
+        }
+    }
+    return found;
+}
+/**
+ * The oversight of the scope.
+ *
+ * The board records of a bean scope are the records of that bean, and every
+ * other scope sees the whole board: the board has no session column and no
+ * window, so a report that narrowed it would be narrowing it by guesswork.
+ */
+export async function oversightFacts(stateRoot, scope, findings) {
+    const records = await boardRecords(stateRoot);
+    const scoped = scope.kind === 'bean' ? records.filter((r) => r.bean === scope.id) : records;
+    const lessons = await listLessons(stateRoot);
+    const waivers = await createWaiverStore(stateRoot).count();
+    const floor = openFloor(findings, scope);
+    return {
+        records: scoped.length,
+        lessons: pendingLessons(lessons).length,
+        memory: memoryCandidates(records),
+        waivers,
+        auditEntries: await auditEntries(stateRoot),
+        openFloor: floor.length,
+        openFloorFindings: floor,
+        mismatches: {
+            known: false,
+            reason: 'no package compares the board with a report',
+        },
+        redactions: {
+            known: false,
+            reason: 'no package keeps a counter',
+        },
+    };
+}
+//# sourceMappingURL=oversight.js.map

package/dist/report/oversight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oversight.js","sourceRoot":"","sources":["../../src/report/oversight.ts"],"names":[],"mappings":"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"}

package/dist/report/policy-firing.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=policy-firing.test.d.ts.map

package/dist/report/policy-firing.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-firing.test.d.ts","sourceRoot":"","sources":["../../src/report/policy-firing.test.ts"],"names":[],"mappings":""}

package/dist/report/policy-firing.test.js

@@ -0,0 +1,68 @@
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { firstPartyPolicyModules, PolicyEngine, PolicyRegistry } from '@openagentsy/hooks';
+import { closeLedger, createPolicyFiringSink, openLedger, topPoliciesByFireCount, } from '@openagentsy/ledger';
+import { describe, expect, it } from 'vitest';
+/**
+ * The firing log, from the engine to the ledger and back (§21.3).
+ *
+ * The engine writes through a sink and the ledger stores the rows, so the
+ * log is a store: it is read back after the ledger was closed and opened
+ * again.
+ */
+describe('the policy firing log', () => {
+    it('holds the firings of a session after the ledger was reopened', () => {
+        const root = mkdtempSync(join(tmpdir(), 'openagentsy-policy-engine-'));
+        const db = openLedger(root);
+        const registry = new PolicyRegistry(firstPartyPolicyModules({ workspace: root }));
+        const engine = new PolicyEngine(registry, { sink: createPolicyFiringSink(db) });
+        engine.evaluate({
+            session: { id: 'ses_1', roleId: 'builder' },
+            response: { text: 'You are absolutely right, this is a great point.' },
+        });
+        closeLedger(db);
+        const again = openLedger(root);
+        try {
+            const counts = topPoliciesByFireCount(again, 10);
+            const flagged = counts.find((entry) => entry.policyId === 'oa.anti-sycophancy');
+            expect(flagged?.count).toBe(1);
+            expect(flagged?.flags).toBe(1);
+            expect(flagged?.versions).toEqual(['1.0.0']);
+            const stack = again
+                .query('SELECT reason, detail FROM policy_firing WHERE policy_id = ?')
+                .get('oa.policy.stack');
+            expect(stack?.reason).toBe('stack-assembled');
+            expect(stack?.detail).toContain('oa.anti-sycophancy');
+        }
+        finally {
+            closeLedger(again);
+        }
+    });
+    it('records the stack of a session once, and the decisions of it', () => {
+        const root = mkdtempSync(join(tmpdir(), 'openagentsy-policy-engine-'));
+        const db = openLedger(root);
+        const registry = new PolicyRegistry(firstPartyPolicyModules({ workspace: root }));
+        const engine = new PolicyEngine(registry, { sink: createPolicyFiringSink(db) });
+        const context = {
+            session: { id: 'ses_1', roleId: 'builder' },
+            response: { text: 'The parser reads the file.' },
+        };
+        engine.evaluate(context);
+        engine.evaluate(context);
+        closeLedger(db);
+        const again = openLedger(root);
+        try {
+            const stack = again
+                .query('SELECT COUNT(*) AS total FROM policy_firing WHERE policy_id = ?')
+                .get('oa.policy.stack');
+            expect(stack.total).toBe(1);
+            const total = again.query('SELECT COUNT(*) AS total FROM policy_firing').get();
+            expect(total.total).toBeGreaterThan(1);
+        }
+        finally {
+            closeLedger(again);
+        }
+    });
+});
+//# sourceMappingURL=policy-firing.test.js.map

package/dist/report/policy-firing.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-firing.test.js","sourceRoot":"","sources":["../../src/report/policy-firing.test.ts"],"names":[],"mappings":"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"}

package/dist/report/scope.d.ts

@@ -0,0 +1,64 @@
+import type { ReportScope } from '@openagentsy/core';
+import type { openLedger } from '@openagentsy/ledger';
+/**
+ * The scope of the report, and the rows it selects.
+ *
+ * A scope is one of three things: a session, a bean or a window. The report
+ * says which one it is, and an empty scope is a fact the report prints
+ * rather than a gap it fills with zeroes.
+ */
+/**
+ * The ledger's database, as the ledger names it.
+ *
+ * The type comes from the ledger rather than from `bun:sqlite`, so the CLI
+ * does not need the Bun type definitions to talk about the ledger it
+ * already opens.
+ */
+export type LedgerDb = ReturnType<typeof openLedger>;
+/** The flags a scope is built from. */
+export type ScopeFlags = {
+    /** The session, and the subagents that rolled up into it. */
+    session?: string | undefined;
+    /** The bean: the rows whose task is that bean. */
+    bean?: string | undefined;
+    /** The window, as a phrase: 30d, 30 days ago, 2 weeks ago. */
+    since?: string | undefined;
+};
+/** The scope the flags name, or the problem with them. */
+export type ScopeResult = {
+    ok: true;
+    scope: ReportScope;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The scope the flags name.
+ *
+ * The flags name one thing. Two of them name two things, and a report of
+ * two scopes at once is a report of none of them, so the command says the
+ * scope is ambiguous and stops.
+ */
+export declare function parseScope(flags: ScopeFlags): ScopeResult;
+/**
+ * Shadow the ledger's tables with the rows the scope selects.
+ *
+ * The ledger's own queries read the tables by name, and they take no scope:
+ * the ledger holds every row it was given. So the scope is applied here,
+ * once, by putting the scoped rows into temp tables of the same names. The
+ * ledger's queries then read the scope, and the report cannot drift from
+ * the ledger, because the report never totals anything itself.
+ *
+ * The temp tables live in the connection and go with it: nothing is written
+ * to the ledger, and a report never changes what it reports on.
+ */
+export declare function shadowScope(db: LedgerDb, scope: ReportScope): void;
+/**
+ * The days the ledger's own window covers.
+ *
+ * The ledger's outcome queries look at the last thirty days. A scope that
+ * names a window uses that window, and a scope that names a thing opens the
+ * ledger's window wide, so the scope alone decides what is in the report.
+ */
+export declare function windowDays(scope: ReportScope): number;
+//# sourceMappingURL=scope.d.ts.map

package/dist/report/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../src/report/scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAErD,uCAAuC;AACvC,MAAM,MAAM,UAAU,GAAG;IACvB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B,CAAC;AAEF,0DAA0D;AAC1D,MAAM,MAAM,WAAW,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AA2C1F;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CAuBzD;AA+CD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAYlE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAErD"}

package/dist/report/scope.js

@@ -0,0 +1,146 @@
+/** How long a unit of a window is, in milliseconds. */
+const UNITS = {
+    h: 3_600_000,
+    hour: 3_600_000,
+    hours: 3_600_000,
+    d: 86_400_000,
+    day: 86_400_000,
+    days: 86_400_000,
+    w: 604_800_000,
+    week: 604_800_000,
+    weeks: 604_800_000,
+    m: 2_592_000_000,
+    month: 2_592_000_000,
+    months: 2_592_000_000,
+};
+/**
+ * The window a phrase names.
+ *
+ * The phrase is a number and a unit, with an optional "ago": 30d, 30 days,
+ * 30 days ago. A phrase that names no window is no window, and the caller
+ * says so rather than guessing a default.
+ */
+function parseWindow(phrase) {
+    const trimmed = phrase
+        .trim()
+        .toLowerCase()
+        .replace(/\s+ago$/, '')
+        .trim();
+    const found = /^(\d+)\s*([a-z]+)$/.exec(trimmed);
+    if (found === null)
+        return undefined;
+    const amount = Number(found[1]);
+    const unit = found[2];
+    if (unit === undefined)
+        return undefined;
+    const millis = UNITS[unit];
+    if (millis === undefined || !Number.isFinite(amount) || amount <= 0)
+        return undefined;
+    const days = Math.round((amount * millis) / 86_400_000);
+    if (days <= 0)
+        return undefined;
+    return { days, label: `${amount} ${unit}` };
+}
+/**
+ * The scope the flags name.
+ *
+ * The flags name one thing. Two of them name two things, and a report of
+ * two scopes at once is a report of none of them, so the command says the
+ * scope is ambiguous and stops.
+ */
+export function parseScope(flags) {
+    const named = [
+        ...(flags.session === undefined ? [] : [`session ${flags.session}`]),
+        ...(flags.bean === undefined ? [] : [`bean ${flags.bean}`]),
+        ...(flags.since === undefined ? [] : [`since ${flags.since}`]),
+    ];
+    if (named.length > 1) {
+        return { ok: false, error: `the scope names more than one thing: ${named.join(' and ')}` };
+    }
+    if (flags.session !== undefined) {
+        return { ok: true, scope: { kind: 'session', id: flags.session } };
+    }
+    if (flags.bean !== undefined) {
+        return { ok: true, scope: { kind: 'bean', id: flags.bean } };
+    }
+    if (flags.since !== undefined) {
+        const window = parseWindow(flags.since);
+        if (window === undefined) {
+            return { ok: false, error: `the window ${flags.since} names no time` };
+        }
+        return { ok: true, scope: { kind: 'since', days: window.days, label: window.label } };
+    }
+    return { ok: true, scope: { kind: 'project' } };
+}
+/** The tables the scope is applied to. */
+const TABLES = ['usage', 'waste', 'outcome', 'policy_firing'];
+/**
+ * The rows a table holds for the scope.
+ *
+ * The predicate is the scope, and the parameters are what it names. A
+ * project scope selects every row, so the predicate is a tautology and the
+ * table is read whole.
+ */
+function predicate(table, scope, instant) {
+    switch (scope.kind) {
+        case 'project':
+            return { sql: '1 = 1', params: [] };
+        case 'since':
+            return { sql: 'ts >= ?', params: [instant] };
+        case 'session':
+            if (table === 'usage') {
+                return { sql: '(root_session_id = ? OR session_id = ?)', params: [scope.id, scope.id] };
+            }
+            if (table === 'policy_firing') {
+                return { sql: 'session_id = ?', params: [scope.id] };
+            }
+            return { sql: 'root_session_id = ?', params: [scope.id] };
+        case 'bean':
+            if (table === 'waste') {
+                return {
+                    sql: 'message_id IN (SELECT message_id FROM main.usage WHERE task_id = ?)',
+                    params: [scope.id],
+                };
+            }
+            if (table === 'policy_firing') {
+                return {
+                    sql: 'session_id IN (SELECT session_id FROM main.usage WHERE task_id = ?)',
+                    params: [scope.id],
+                };
+            }
+            return { sql: 'task_id = ?', params: [scope.id] };
+    }
+}
+/**
+ * Shadow the ledger's tables with the rows the scope selects.
+ *
+ * The ledger's own queries read the tables by name, and they take no scope:
+ * the ledger holds every row it was given. So the scope is applied here,
+ * once, by putting the scoped rows into temp tables of the same names. The
+ * ledger's queries then read the scope, and the report cannot drift from
+ * the ledger, because the report never totals anything itself.
+ *
+ * The temp tables live in the connection and go with it: nothing is written
+ * to the ledger, and a report never changes what it reports on.
+ */
+export function shadowScope(db, scope) {
+    const instant = scope.kind === 'since'
+        ? new Date(Date.now() - scope.days * 86_400_000).toISOString()
+        : new Date(0).toISOString();
+    for (const table of TABLES) {
+        const { sql, params } = predicate(table, scope, instant);
+        db.exec(`DROP TABLE IF EXISTS temp.${table}`);
+        db.query(`CREATE TEMP TABLE ${table} AS SELECT * FROM main.${table} WHERE ${sql}`).run(...params);
+    }
+}
+/**
+ * The days the ledger's own window covers.
+ *
+ * The ledger's outcome queries look at the last thirty days. A scope that
+ * names a window uses that window, and a scope that names a thing opens the
+ * ledger's window wide, so the scope alone decides what is in the report.
+ */
+export function windowDays(scope) {
+    return scope.kind === 'since' ? scope.days : 36_500;
+}
+//# sourceMappingURL=scope.js.map

package/dist/report/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../../src/report/scope.ts"],"names":[],"mappings":"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"}

package/dist/who.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Who the person running a command is.
+ *
+ * A decision a person makes carries the name of the person who made it. The
+ * name comes from the environment when it is set, because a person may want
+ * the record to say who they are, and the default is "a person".
+ */
+export declare function deciderBy(override?: string): string;
+//# sourceMappingURL=who.d.ts.map

package/dist/who.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"who.d.ts","sourceRoot":"","sources":["../src/who.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD"}

package/dist/who.js

@@ -0,0 +1,11 @@
+/**
+ * Who the person running a command is.
+ *
+ * A decision a person makes carries the name of the person who made it. The
+ * name comes from the environment when it is set, because a person may want
+ * the record to say who they are, and the default is "a person".
+ */
+export function deciderBy(override) {
+    return override ?? process.env.OPENAGENTSY_USER ?? 'human';
+}
+//# sourceMappingURL=who.js.map

package/dist/who.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"who.js","sourceRoot":"","sources":["../src/who.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,QAAiB;IACzC,OAAO,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,OAAO,CAAC;AAC7D,CAAC"}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@voxslopuli/openagentsy",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "type": "module",
+  "bin": {
+    "openagentsy": "./dist/index.js",
+    "oa": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json && chmod +x dist/index.js && node scripts/copy-plugin.mjs",
+    "typecheck": "tsc -b tsconfig.json"
+  },
+  "dependencies": {
+    "@openagentsy/core": "^0.2.0",
+    "@openagentsy/footprint": "^0.2.0",
+    "@openagentsy/hooks": "^0.2.0",
+    "@openagentsy/ledger": "^0.2.0",
+    "@openagentsy/models": "^0.2.0",
+    "@openagentsy/quality": "^0.2.0",
+    "jsonc-parser": "^3.3.1",
+    "yaml": "^2.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "typescript": "^5.9.2",
+    "@openagentsy/adapter-opencode": "0.2.0"
+  },
+  "description": "The hub and spoke agent system for OpenCode: one Lead, many specialists, one writer per file.",
+  "license": "GPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/voxslopuli/openagentsy.git"
+  },
+  "homepage": "https://github.com/voxslopuli/openagentsy#readme",
+  "bugs": {
+    "url": "https://github.com/voxslopuli/openagentsy/issues"
+  },
+  "keywords": [
+    "agents",
+    "opencode",
+    "coordination",
+    "leases",
+    "mcp",
+    "bun"
+  ],
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "plugin"
+  ]
+}