@jitsusama/agentic-harness.core 0.1.0 → 0.3.0

package/dist/bin/cli.js

@@ -27,6 +27,7 @@ import { runNotesAction } from "./notes.js";
 import { processExec } from "./process-exec.js";
 import { runQuestAction } from "./quest.js";
 import { runSlackAuthLogin, runSlackAuthStatus } from "./slack-auth.js";
+import { runWebCheck } from "./web.js";
 /** Where a loop's state lives when the caller doesn't override it. */
 const DEFAULT_STATE_FILE = ".agentic-harness/tdd-loop.json";
 /** Where quest state lives when the caller doesn't override it. */
@@ -218,6 +219,12 @@ async function main() {
             return;
         }
     }
+    if (options.domain === "web" && options.command === "check") {
+        const result = await runWebCheck(await readStdin());
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+        process.exitCode = result.ok ? 0 : 1;
+        return;
+    }
     if (options.domain === "slack-auth") {
         if (options.command === "status") {
             process.stdout.write(`${JSON.stringify(await runSlackAuthStatus())}\n`);

package/dist/bin/web.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The web check commands: one browser, one page, one verdict.
+ *
+ * This is the CLI adapter for the judgment checks a hook-and-skill
+ * consumer cannot reach through a library import: it opens a
+ * session, runs one check against one URL and answers JSON with
+ * the same rendered report the pi tools show. Stateless per
+ * invocation like every other command here; the browser lives and
+ * dies inside the call.
+ */
+/** The checks this command knows how to run. */
+export declare const WEB_CHECK_KINDS: readonly ["motion", "typography", "hydration", "perf"];
+/** What arrives on stdin. */
+export interface WebCheckInput {
+    readonly kind: string;
+    readonly url: string;
+    /** For perf: how many loads to sample. Defaults to 3. */
+    readonly samples?: number;
+}
+/** What goes out on stdout. */
+export interface WebCheckOutput {
+    readonly ok: boolean;
+    readonly kind?: string;
+    readonly url?: string;
+    /** The same rendered verdict the pi tools show. */
+    readonly report?: string;
+    readonly error?: string;
+}
+/** Run one web check against one URL. */
+export declare function runWebCheck(raw: string): Promise<WebCheckOutput>;

package/dist/bin/web.js

@@ -0,0 +1,97 @@
+/**
+ * The web check commands: one browser, one page, one verdict.
+ *
+ * This is the CLI adapter for the judgment checks a hook-and-skill
+ * consumer cannot reach through a library import: it opens a
+ * session, runs one check against one URL and answers JSON with
+ * the same rendered report the pi tools show. Stateless per
+ * invocation like every other command here; the browser lives and
+ * dies inside the call.
+ */
+import { tallyFindings } from "../web/audit/index.js";
+import { analyseMotion } from "../web/audit/motion.js";
+import { renderAudit } from "../web/audit/report.js";
+import { analyseTypography, renderTypography, } from "../web/design/typography.js";
+import { judgeHydration, renderHydration } from "../web/hydration/index.js";
+import { measureSamples, renderVitals } from "../web/perf/index.js";
+import { BrowserSession } from "../web/session.js";
+/** The checks this command knows how to run. */
+export const WEB_CHECK_KINDS = [
+    "motion",
+    "typography",
+    "hydration",
+    "perf",
+];
+/** Perf samples when the caller does not say. */
+const DEFAULT_SAMPLES = 3;
+/** The most loads one perf call will pay for. */
+const MAX_SAMPLES = 9;
+function isKind(kind) {
+    return WEB_CHECK_KINDS.includes(kind);
+}
+async function checkOn(session, kind, input) {
+    if (kind === "perf") {
+        const wanted = Math.min(Math.max(1, Math.round(input.samples ?? DEFAULT_SAMPLES)), MAX_SAMPLES);
+        const samples = [await session.vitals()];
+        while (samples.length < wanted) {
+            const { failure } = await session.reload();
+            // A reload that failed ends the sampling rather than the
+            // check: the loads that did land are still a measurement.
+            if (failure)
+                break;
+            samples.push(await session.vitals());
+        }
+        const last = samples[samples.length - 1];
+        return renderVitals(last, measureSamples(samples));
+    }
+    if (kind === "motion") {
+        const findings = analyseMotion(await session.motionUnderReduce());
+        return renderAudit(findings, tallyFindings(findings), {
+            measured: "Emulated prefers-reduced-motion: reduce, reloaded, and read " +
+                "what was still moving.",
+        });
+    }
+    if (kind === "typography") {
+        const blocks = await session.typography();
+        return renderTypography(blocks, analyseTypography(blocks));
+    }
+    const capture = await session.hydration();
+    const lines = session
+        .logs()
+        .entries.map(({ item }) => ({ level: item.level, text: item.text }));
+    return renderHydration(judgeHydration(capture, lines));
+}
+/** Run one web check against one URL. */
+export async function runWebCheck(raw) {
+    let input;
+    try {
+        input = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, error: "stdin must be JSON: { kind, url }" };
+    }
+    if (!input.url) {
+        return { ok: false, error: "url is required" };
+    }
+    if (!input.kind || !isKind(input.kind)) {
+        return {
+            ok: false,
+            error: `kind must be one of: ${WEB_CHECK_KINDS.join(", ")}`,
+        };
+    }
+    const session = await BrowserSession.open(`web-check-${process.pid}`);
+    try {
+        const { failure, status } = await session.navigate(input.url);
+        if (failure) {
+            return { ok: false, error: `Could not load ${input.url}: ${failure}` };
+        }
+        if (status !== undefined && status >= 400) {
+            return { ok: false, error: `${input.url} answered ${status}` };
+        }
+        const report = await checkOn(session, input.kind, input);
+        return { ok: true, kind: input.kind, url: input.url, report };
+    }
+    finally {
+        await session.close();
+    }
+}

package/dist/observability/index.d.ts

@@ -7,7 +7,15 @@
  * own database file. Rows are queryable on demand, roll up
  * into periodic per-model and per-persona summaries before
  * they age out, and drive a compact status-line figure.
+ *
+ * The ledger beside it covers the other side of the bill: the
+ * main loop's own turns, addressed by content so a total can
+ * be trusted.
+ *
+ * Reading a harness's log format into those turns is that
+ * harness's own business and lives in its package.
  */
+export { type CallScope, type CostDimension, type CostSlice, type DroppedCallRecord, type LedgerTotal, openTurnStore, type PaybackReplay, type RecordOutcome, type Regret, type RegretReport, type RepeatedCall, type SessionRecord, type ToolCallRecord, type TurnKind, type TurnRecord, type TurnStore, type VerifierKind, type VerifierOutcome, } from "./ledger/index.js";
 export { type RunRecorder, type RunRecordInput, recordRunEverywhere, registerRunRecorder, runRecordFrom, } from "./recorder.js";
 export { openRunStore, type RunQuery, type RunStore } from "./store.js";
 export type { RunCost, RunRecord, RunRollup, RunSummary, RunTokens, VerifyOutcome, } from "./types.js";

package/dist/observability/index.js

@@ -7,6 +7,14 @@
  * own database file. Rows are queryable on demand, roll up
  * into periodic per-model and per-persona summaries before
  * they age out, and drive a compact status-line figure.
+ *
+ * The ledger beside it covers the other side of the bill: the
+ * main loop's own turns, addressed by content so a total can
+ * be trusted.
+ *
+ * Reading a harness's log format into those turns is that
+ * harness's own business and lives in its package.
  */
+export { openTurnStore, } from "./ledger/index.js";
 export { recordRunEverywhere, registerRunRecorder, runRecordFrom, } from "./recorder.js";
 export { openRunStore } from "./store.js";

package/dist/observability/ledger/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The ledger: a store of billable turns, and what one is.
+ *
+ * Cost is derived from the logs a harness already writes rather than
+ * recorded a second time, so there is exactly one writer of the truth
+ * and the ledger can be rebuilt from scratch whenever its shape
+ * changes.
+ *
+ * Reading those logs is not here. A turn is a portable idea; the format
+ * it was written in is not, so each harness parses its own and hands
+ * over records. This module knows what a turn is and where to keep it.
+ */
+export { type CostDimension, type CostSlice, type LedgerTotal, openTurnStore, type RecordOutcome, type TurnStore, } from "./store.js";
+export type { CallScope, DroppedCallRecord, PaybackReplay, Regret, RegretReport, RepeatedCall, SessionRecord, ToolCallRecord, TurnKind, TurnRecord, VerifierKind, VerifierOutcome, } from "./types.js";

package/dist/observability/ledger/index.js

@@ -0,0 +1,13 @@
+/**
+ * The ledger: a store of billable turns, and what one is.
+ *
+ * Cost is derived from the logs a harness already writes rather than
+ * recorded a second time, so there is exactly one writer of the truth
+ * and the ledger can be rebuilt from scratch whenever its shape
+ * changes.
+ *
+ * Reading those logs is not here. A turn is a portable idea; the format
+ * it was written in is not, so each harness parses its own and hands
+ * over records. This module knows what a turn is and where to keep it.
+ */
+export { openTurnStore, } from "./store.js";

package/dist/observability/ledger/store.d.ts

@@ -0,0 +1,50 @@
+import type { CallScope, DroppedCallRecord, PaybackReplay, RegretReport, RepeatedCall, SessionRecord, ToolCallRecord, TurnRecord, VerifierOutcome } from "./types.js";
+/** What a dimension's slice of spend came to. */
+export interface CostSlice {
+    readonly key: string;
+    readonly cost: number;
+    readonly turns: number;
+}
+/** Everything the ledger holds, with its own blind spots stated. */
+export interface LedgerTotal {
+    readonly cost: number;
+    readonly turns: number;
+    /** Turns held with no cost, so a total can say what it is missing. */
+    readonly unmetered: number;
+    readonly cacheWriteTokens: number;
+    /** Of those, the ones billed at the one-hour rate. */
+    readonly cacheWrite1hTokens: number;
+}
+/** How many turns a write added, and how many it had already seen. */
+export interface RecordOutcome {
+    readonly inserted: number;
+    readonly duplicates: number;
+}
+/** What a total or a slice may be narrowed to. */
+export type CostDimension = "model" | "session" | "kind" | "day" | "repo" | "quest";
+/** A content-addressed store of billable turns. */
+export interface TurnStore {
+    recordTurns(turns: readonly TurnRecord[]): Promise<RecordOutcome>;
+    recordSession(session: SessionRecord): Promise<void>;
+    recordCalls(calls: readonly ToolCallRecord[]): Promise<RecordOutcome>;
+    queryCalls(): Promise<ToolCallRecord[]>;
+    /** Arguments asked more than once in one session, heaviest first. */
+    repeatedCalls(scope?: CallScope): Promise<RepeatedCall[]>;
+    recordDropped(dropped: readonly DroppedCallRecord[]): Promise<RecordOutcome>;
+    queryDropped(): Promise<DroppedCallRecord[]>;
+    /** Dropped calls asked again after the drop, with how many could have been. */
+    regret(scope?: CallScope): Promise<RegretReport>;
+    /** Pass, fail and unknown counts per verifier kind that ran at all. */
+    verifierOutcomes(): Promise<VerifierOutcome[]>;
+    /** How real compactions compare against the payback test. */
+    paybackReplay(): Promise<PaybackReplay>;
+    total(): Promise<LedgerTotal>;
+    costBy(dimension: CostDimension): Promise<CostSlice[]>;
+    close(): Promise<void>;
+}
+/**
+ * Open (creating if needed) a turn ledger at the given path. Safe to
+ * point at the same file as the run store: the tables are disjoint and
+ * WAL keeps readers clear of the single writer.
+ */
+export declare function openTurnStore(dbPath: string): Promise<TurnStore>;