@tryvitris/website-harness 0.0.0-stage → 0.1.0-beta.5

package/bin/types/src/agent/invocation-budget.d.ts

@@ -0,0 +1,32 @@
+import { type UsageReceipt } from "./artifacts.ts";
+import type { AgentState } from "./graph.ts";
+export type Invocation = {
+    version: 1;
+    id: string;
+    preparationId: string;
+    nodeId: string;
+    status: "reserved" | "settled";
+    reservedTokens: number;
+    startedAt: string;
+    receipt?: UsageReceipt;
+};
+export declare function readInvocations(root: string): Invocation[];
+export declare function invocationSpend(root: string): {
+    calls: number;
+    inputTokens: number;
+    outputTokens: number;
+    tokens: number;
+    durationMs: number;
+    reservedTokens: number;
+    unknownCalls: number;
+};
+export declare function syncInvocationSpend(root: string, state: AgentState): void;
+export declare function reserveInvocation(opts: {
+    root: string;
+    preparationId: string;
+    nodeId: string;
+    maxTokens: number;
+    totalTokenLimit?: number;
+    otherTokens?: number;
+}): Invocation;
+export declare function settleInvocation(root: string, id: string, receipt: UsageReceipt): Invocation;

package/bin/types/src/agent/jev/agent-usage.d.ts

@@ -0,0 +1,165 @@
+import type { UsageReceipt } from "../artifacts.ts";
+export type AgentUsageSource = "host_export" | "structured_log" | "manual_host_report" | "unavailable";
+export type AgentUsageCoverage = "measured" | "partial" | "unknown";
+export interface AgentAttemptReceipt {
+    schemaVersion: 1;
+    receiptId: string;
+    runId?: string;
+    arm?: "A" | "B" | "C";
+    nodeId: string;
+    preparationId: string;
+    attemptId: string;
+    kind: "agent" | "tool" | "critic";
+    provider?: string;
+    model?: string;
+    sessionId?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    wallTimeMs?: number;
+    source: AgentUsageSource;
+    coverage: AgentUsageCoverage;
+    rawEvidencePath?: string;
+    rawEvidenceHash?: string;
+    createdAt: string;
+}
+export declare function agentUsageDir(root: string): string;
+export declare function logicalUsageKey(opts: {
+    runId?: string;
+    nodeId: string;
+    preparationId: string;
+    attemptId: string;
+}): string;
+export declare function writeAgentAttemptReceipt(root: string, receipt: AgentAttemptReceipt): string;
+export declare function recordAgentStageAttempt(opts: {
+    root: string;
+    nodeId: string;
+    preparationId: string;
+    attemptId: string;
+    kind: "agent" | "tool" | "critic";
+    runId?: string;
+    arm?: "A" | "B" | "C";
+    provider?: string;
+    model?: string;
+    sessionId?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    wallTimeMs?: number;
+    source: AgentUsageSource;
+    rawEvidencePath?: string;
+    rawEvidenceHash?: string;
+    adapterReceipt?: UsageReceipt;
+}): AgentAttemptReceipt;
+export declare function loadAgentAttemptReceipts(root: string): AgentAttemptReceipt[];
+export interface AgentUsageAggregate {
+    coverage: AgentUsageCoverage | "incomplete";
+    attempts: number;
+    agentAttempts: number;
+    toolAttempts: number;
+    criticAttempts: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    unknownAttempts: number;
+    missingRequired: boolean;
+    byNode: Record<string, {
+        coverage: AgentUsageCoverage | "incomplete";
+        inputTokens?: number;
+        outputTokens?: number;
+        attempts: number;
+    }>;
+}
+export interface RunScopeMatch {
+    runId?: string;
+    arm?: "A" | "B" | "C";
+    provider?: string;
+    model?: string;
+    sessionId?: string;
+}
+export declare function selectAuthoritativeRunReceipt(receipts: AgentAttemptReceipt[], scope?: RunScopeMatch): {
+    receipt?: AgentAttemptReceipt;
+    conflict: boolean;
+};
+export declare function aggregateAgentUsage(receipts: AgentAttemptReceipt[], requiredAgentNodes?: string[], scope?: RunScopeMatch): AgentUsageAggregate;
+export declare function compareAgentUsageArms(a: AgentUsageAggregate, b: AgentUsageAggregate): {
+    verdict: "ok" | "measurement_incomplete";
+    savingsPct: number | null;
+    agentTokenDelta: number | null;
+};
+export declare function tokensFromNestedUsage(raw: unknown): {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    cacheReadTokens?: number;
+    unknown: boolean;
+};
+export type HostUsageScope = "attempt" | "run";
+export interface HostUsageImport {
+    schemaVersion: 1;
+    provider: string;
+    model: string;
+    sessionId: string;
+    rawExportPath: string;
+    rawExportHash: string;
+    sourceFormat: string;
+    sourceFormatVersion: string;
+    scope: HostUsageScope;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    runId?: string;
+    arm?: "A" | "B" | "C";
+    nodeId?: string;
+    preparationId?: string;
+    attemptId?: string;
+}
+export declare function isCompleteHostUsageContract(raw: unknown): raw is HostUsageImport;
+export declare function verifyHostExportEvidence(opts: {
+    evidenceRoot: string;
+    contract: HostUsageImport;
+}): {
+    ok: true;
+    canonicalPath: string;
+    hash: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function importHostUsage(opts: {
+    root: string;
+    raw: unknown;
+    evidenceRoot?: string;
+    fallbackProvider?: string;
+    expected?: RunScopeMatch;
+}): AgentAttemptReceipt;
+/** Gemini CLI adapter. Arbitrary token JSON is not a host_export. */
+export declare function importGeminiHostUsage(opts: {
+    root: string;
+    raw: unknown;
+    runId: string;
+    sessionId?: string;
+    nodeId?: string;
+    preparationId?: string;
+    attemptId?: string;
+    kind?: "agent" | "critic";
+}): AgentAttemptReceipt;
+export interface ExpectedAttempt {
+    nodeId: string;
+    kind: "agent" | "critic" | "tool";
+    preparationId: string;
+    attemptId: string;
+}
+export declare function expectedAttemptsFromWorkflow(root: string): ExpectedAttempt[];
+export declare function reconcileExpectedAttempts(receipts: AgentAttemptReceipt[], expected: Array<{
+    nodeId: string;
+    kind: "agent" | "critic" | "tool";
+    preparationId?: string;
+    attemptId?: string;
+}>): {
+    coverage: "complete" | "incomplete";
+    missing: string[];
+};

package/bin/types/src/agent/jev/batching.d.ts

@@ -0,0 +1,101 @@
+import type { Question } from "./types.ts";
+import type { JevClient } from "./client.ts";
+export interface BatchableQuestion {
+    id: string;
+    taskType: "grounding" | "cta_consistency" | "coverage" | "custom";
+    questionKey?: string;
+    question?: Question;
+    claimId?: string;
+    claim?: string;
+    evidenceId?: string;
+    evidenceExcerpt?: string;
+    source?: string;
+    dependsOn?: string[];
+    metadata?: Record<string, unknown>;
+}
+export interface BatchPartition {
+    batchId: string;
+    taskType: "grounding" | "cta_consistency" | "coverage" | "custom";
+    questions: Record<string, Question>;
+    state: {
+        task: string;
+        claims: Record<string, {
+            id: string;
+            claim: string;
+        }>;
+        evidence: Record<string, {
+            id: string;
+            source: string;
+            hash: string;
+            excerpt: string;
+            aliases?: string[];
+        }>;
+        metadata?: Record<string, unknown>;
+    };
+    questionIds: string[];
+    questionKeyMap: Record<string, string>;
+    estimatedUnbatchedTokens: number;
+    payloadChars: number;
+}
+export interface BatchingBudgetConfig {
+    maxQuestionsPerBatch: number;
+    maxPayloadChars: number;
+    taskDeadlineMs: number;
+    maxRetries: number;
+}
+export declare const DEFAULT_BATCHING_BUDGET: BatchingBudgetConfig;
+export interface BatchMetrics {
+    totalQuestions: number;
+    deferredCount: number;
+    rejectedOversizedCount: number;
+    batchesCount: number;
+    unbatchedTransportCalls: number;
+    actualTransportCalls: number;
+    transportCallSavingsPct: number;
+    measured: boolean;
+    observedInputTokens: number | null;
+    observedOutputTokens: number | null;
+    observedTotalTokens: number | null;
+    estimatedUnbatchedTokens: number;
+    estimatedBatchedTokens: number;
+    estimatedTokenSavingsPct: number;
+    actualTokenSavingsPct: number | null;
+    unbatchedEstimatedTokens: number;
+    batchedActualTokens: number;
+    tokenSavingsPct: number;
+    durationMs: number;
+}
+export interface BatchExecutionResult {
+    answers: Record<string, unknown>;
+    metrics: BatchMetrics;
+    receipts: string[];
+    itemReceipts: Record<string, string>;
+    deferredItems: BatchableQuestion[];
+    rejectedOversizedItems?: BatchableQuestion[];
+}
+/**
+ * Partitions batchable questions into bounded batches with shared-state deduplication.
+ * Independent questions sharing evidence are grouped.
+ * Dependent questions whose evidence or prerequisite is not yet satisfied are deferred.
+ * Enforces total input size, question count limits, and payload size bounds.
+ */
+export declare function partitionBatchItems(items: BatchableQuestion[], options?: {
+    config?: Partial<BatchingBudgetConfig>;
+    completedPrerequisites?: Set<string>;
+    throwOnOversized?: boolean;
+}): {
+    partitions: BatchPartition[];
+    deferredDependentItems: BatchableQuestion[];
+    rejectedOversizedItems: BatchableQuestion[];
+};
+/**
+ * Executes partitioned batches via JevClient with transport calls and token telemetry.
+ * Enforces deadlines and reports savings between unbatched vs batched execution.
+ */
+export declare function executeBatches(opts: {
+    client: JevClient;
+    partitions: BatchPartition[];
+    signal?: AbortSignal;
+    deadlineMs?: number;
+    nodeId?: string;
+}): Promise<BatchExecutionResult>;

package/bin/types/src/agent/jev/block-catalog.d.ts

@@ -0,0 +1,95 @@
+import { blockPreviewEvidence, type BlockMeta } from "../../blocks/metadata.ts";
+export type FitLabel = "good-start" | "needs-adaptation" | "no-fit";
+export interface BlockSlot {
+    name: string;
+    required: boolean;
+    description: string;
+}
+export interface BlockRecord {
+    id: string;
+    category: string;
+    name: string;
+    look: string;
+    media: string;
+    mediaRequired: boolean;
+    registers: string[];
+    variants: string[];
+    slots: BlockSlot[];
+    interaction: "static" | "island";
+    mobile: {
+        hasMediaQuery: boolean;
+        notes: string;
+    };
+    geometry: string[];
+    example: string;
+    examplePath: string;
+    previewPath?: string;
+    previewHash?: string;
+    seesImages: false;
+    dir: string;
+    meta?: BlockMeta;
+    metadataSource?: "block.meta.json" | "legacy-readme";
+    previewEvidence?: ReturnType<typeof blockPreviewEvidence>;
+}
+export interface BlockLibrary {
+    generatedFrom: "readme+index+template";
+    blocks: BlockRecord[];
+}
+export declare function loadBlockLibrary(kernel?: string): BlockLibrary;
+export declare function validateBlockLibrary(lib: BlockLibrary, kernel?: string): string[];
+export interface StoryboardSectionCase {
+    id: string;
+    siteType: string;
+    role: string;
+    visitorJob: string;
+    mediaCount: number;
+    mediaAspect?: string;
+    interaction?: string;
+    textLength: number;
+    expectedFit: Record<string, FitLabel>;
+    missingJob?: string;
+}
+export declare const BLOCK_COVERAGE_CASES: StoryboardSectionCase[];
+export declare function auditBlockCoverage(lib: BlockLibrary, cases?: StoryboardSectionCase[]): {
+    gaps: Array<{
+        caseId: string;
+        missingJob?: string;
+        noFit: boolean;
+    }>;
+    labeled: Array<{
+        caseId: string;
+        blockId: string;
+        fit: FitLabel;
+    }>;
+};
+export interface SectionState {
+    sectionId: string;
+    pagePath: string;
+    visitorJob: string;
+    requiredActions: string[];
+    textLength: number;
+    textContentIdentity?: string;
+    mediaCount: number;
+    mediaAspect?: string;
+    mediaIds?: string[];
+    mediaDescriptors?: string[];
+    emphasis?: string;
+    pageRole?: string;
+    pageVisitorOutcome?: string;
+    sectionRole?: string;
+    sectionPurpose?: string;
+    decisionIds?: string[];
+    constraints?: string[];
+    contentShape?: string;
+    interaction?: string;
+    adjacentRoles?: string[];
+    adjacentSectionIds?: string[];
+    neighborPurposes?: string[];
+    repetitionRationale?: string;
+    layoutFamily?: string;
+    sourceIds?: string[];
+    sourceHashes?: string[];
+}
+export declare function libraryContentHash(lib: BlockLibrary): string;
+export declare function hardFilterBlocks(lib: BlockLibrary, state: SectionState): BlockRecord[];
+export declare function lexicalShortlist(lib: BlockLibrary, state: SectionState, limit?: number): BlockRecord[];

package/bin/types/src/agent/jev/bounds.d.ts

@@ -0,0 +1,30 @@
+import { type BatchableQuestion } from "./batching.ts";
+export interface JevTaskBounds {
+    maxCandidates: number;
+    maxQuestions: number;
+    maxInputBytes: number;
+    maxTransportAttempts: number;
+    maxWallTimeMs: number;
+}
+export declare const DEFAULT_TASK_BOUNDS: JevTaskBounds;
+export interface BoundOverflow {
+    droppedIds: string[];
+    reason: string;
+    agentObligation: string;
+}
+export declare function applyQuestionFanoutBounds<T extends {
+    id: string;
+}>(items: T[], bounds?: Partial<JevTaskBounds>): {
+    kept: T[];
+    overflow: BoundOverflow | undefined;
+};
+export declare function recordPrepBounds(root: string, preparationId: string, used: {
+    questions: number;
+    candidates: number;
+    overflow?: BoundOverflow;
+}): void;
+export declare function loadPrepBounds(root: string, preparationId: string): {
+    questions: number;
+    overflow?: BoundOverflow;
+} | undefined;
+export declare function overflowAsBatchRejects(overflow: BoundOverflow | undefined, items: BatchableQuestion[]): BatchableQuestion[];

package/bin/types/src/agent/jev/budget.d.ts

@@ -0,0 +1,76 @@
+import type { JevPilotBudget } from "./types.ts";
+export interface JevAggregatedSpend {
+    calls: number;
+    inputTokens: number;
+    outputTokens: number;
+    durationMs: number;
+    cacheHits: number;
+    transportAttempts: number;
+    retries: number;
+    unavailableCalls: number;
+    inFlightReservations: number;
+    inFlightAttempts: number;
+}
+export declare function emptySpend(): JevAggregatedSpend;
+/** Reservation is live if heartbeat is this fresh, even if createdAt is hours old. */
+export declare const RESERVATION_HEARTBEAT_STALE_MS = 30000;
+export interface PilotReservation {
+    reservationId: string;
+    createdAt: string;
+    heartbeatAt: string;
+    ownerPid: number;
+    ownerToken: string;
+    estimatedInputTokens: number;
+    reservedAttempts: number;
+}
+export declare function isPidAlive(pid: number): boolean;
+export declare function isReservationLive(rec: PilotReservation, nowMs?: number, staleMs?: number): boolean;
+export declare function reapStaleReservations(root: string, nowMs?: number): number;
+export declare function loadPilotReservations(root: string, nowMs?: number): PilotReservation[];
+export declare function aggregateJevReceiptSpend(root: string, baseline?: Partial<JevAggregatedSpend>): JevAggregatedSpend;
+export declare function resolvePilotBudget(budget?: JevPilotBudget): JevPilotBudget;
+export declare function estimateInputTokens(payload: unknown): number;
+export declare function remainingPilotBudget(root: string, budget?: JevPilotBudget): {
+    transportAttempts: number;
+    inputTokens: number;
+};
+export declare function withBudgetLock<T>(root: string, fn: () => T | Promise<T>, timeoutMs?: number): Promise<T>;
+export declare function acquirePilotReservation(opts: {
+    root: string;
+    budget?: JevPilotBudget;
+    estimatedInputTokens: number;
+}): Promise<{
+    ok: true;
+    reservationId: string;
+    reservedAttempts: number;
+} | {
+    ok: false;
+    reason: string;
+}>;
+export declare function touchPilotReservation(root: string, reservationId: string): Promise<void>;
+export declare function acquireExtraAttempt(opts: {
+    root: string;
+    reservationId: string;
+    budget?: JevPilotBudget;
+}): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+export declare function commitPilotReservation(opts: {
+    root: string;
+    reservationId: string;
+    writeReceipt?: () => void;
+}): Promise<void>;
+/** @deprecated Use acquirePilotReservation; kept for call sites that only need a read check. */
+export declare function reservePilotTransport(opts: {
+    root: string;
+    budget?: JevPilotBudget;
+    estimatedInputTokens: number;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};

package/bin/types/src/agent/jev/business-draft.d.ts

@@ -0,0 +1,103 @@
+import { type StructuredFact } from "./extraction.ts";
+import type { JevClient } from "./client.ts";
+import type { JevConfig } from "./types.ts";
+/** Single-value fields use Choice + no_match even when several distinct spans exist. */
+export declare const SINGLE_VALUE_FIELDS: SourceFieldKind[];
+/** Multi-value fields use per-candidate Noul; several legitimate values are not a conflict. */
+export declare const MULTI_VALUE_FIELDS: SourceFieldKind[];
+export declare const FIELD_CANDIDATE_NOUL_ACCEPT = 0.85;
+export declare const FIELD_CANDIDATE_NOUL_REJECT = 0.15;
+export declare function isSingleValueField(field: SourceFieldKind): boolean;
+export type SourceFieldKind = "phone" | "email" | "hours" | "offer" | "location" | "credential";
+export interface FieldCandidate {
+    id: string;
+    field: SourceFieldKind;
+    value: string;
+    source: string;
+    excerpt: string;
+    span?: [number, number];
+}
+export interface SelectedField {
+    field: SourceFieldKind;
+    value: string;
+    source: string;
+    excerpt: string;
+    candidateId: string;
+    confidence: number;
+    noul?: number;
+    probabilities?: Record<string, number>;
+}
+export interface UnresolvedField {
+    field: SourceFieldKind;
+    reason: "no_match" | "conflict" | "uncertain" | "unavailable" | "no_candidates" | "incomplete";
+    candidateIds: string[];
+    notes: string;
+}
+export interface FieldCoverage {
+    field: SourceFieldKind;
+    cardinality: "single" | "multi";
+    candidateCount: number;
+    evaluatedCount: number;
+    complete: boolean;
+}
+export interface RawFieldJudgment {
+    questionId: string;
+    field: SourceFieldKind;
+    candidateId?: string;
+    type: "choice" | "noul";
+    choice?: string;
+    noul?: number;
+    confidence?: number;
+    probabilities?: Record<string, number>;
+}
+export interface MachineBusinessDraft {
+    schemaVersion: 1;
+    selected: SelectedField[];
+    unresolved: UnresolvedField[];
+    conflicts: Array<{
+        field: SourceFieldKind;
+        values: string[];
+        candidateIds: string[];
+    }>;
+    candidateCoverage: FieldCoverage[];
+    rawJudgments: RawFieldJudgment[];
+    investigationObligations: string[];
+}
+export declare const TRANSCRIPTION_BLOCK_START = "<!-- jev-transcription:start -->";
+export declare const TRANSCRIPTION_BLOCK_END = "<!-- jev-transcription:end -->";
+export declare const DRAFT_BLOCK_START = "<!-- jev-business-draft:start -->";
+export declare const DRAFT_BLOCK_END = "<!-- jev-business-draft:end -->";
+export declare function fieldKindFromFact(fact: StructuredFact): SourceFieldKind | undefined;
+export declare function verbatimValue(fact: StructuredFact, kind: SourceFieldKind): string;
+export declare function buildFieldCandidates(facts: StructuredFact[]): FieldCandidate[];
+export declare function groupByField(candidates: FieldCandidate[]): Map<SourceFieldKind, FieldCandidate[]>;
+export declare function uniqueCandidates(cands: FieldCandidate[]): FieldCandidate[];
+export declare function emptyDraft(): MachineBusinessDraft;
+export declare function fieldTranscriptionRemovable(draft: MachineBusinessDraft, field: SourceFieldKind): boolean;
+export declare function formatMachineDraft(draft: MachineBusinessDraft): string;
+export declare function formatTranscriptionObligations(fields: SourceFieldKind[]): string;
+export declare function applyBusinessAuthorPacketReduction(opts: {
+    packet: string;
+    eligible: boolean;
+    draft: MachineBusinessDraft;
+}): {
+    packet: string;
+    reduced: boolean;
+    removedFields: SourceFieldKind[];
+};
+export declare function saveMachineDraft(root: string, preparationId: string, draft: MachineBusinessDraft): string;
+export declare function loadMachineDraft(root: string, preparationId: string): MachineBusinessDraft | undefined;
+export declare function runBusinessSourceSelection(opts: {
+    root: string;
+    client: JevClient;
+    nodeId: string;
+    preparationId: string;
+    inputHash?: string;
+    jevConfig?: JevConfig;
+    signal?: AbortSignal;
+}): Promise<{
+    draft: MachineBusinessDraft;
+    coveredFieldIds: string[];
+    retainedFieldIds: string[];
+    status: "completed" | "cached" | "no_candidates" | "unavailable";
+}>;