harnery 0.35.0 → 0.37.0

package/dist/core/conversations/query.js

@@ -0,0 +1,280 @@
+import { normalizeConversationRecord } from "./normalize.js";
+export async function queryConversationCatalog(catalog, request) {
+    validateRequest(request);
+    const started = performance.now();
+    const deadline = started + request.budgets.max_wall_ms;
+    const controller = new AbortController();
+    const records = [];
+    const snapshots = [];
+    let decodedBytes = 0;
+    let sourceRecords = 0;
+    let sourceTruncation;
+    const providers = request.provider_id ? [catalog.require(request.provider_id)] : catalog.list();
+    try {
+        providerLoop: for (const provider of providers) {
+            if (!provider.capabilities.can_list || !provider.capabilities.can_stream_source)
+                continue;
+            if (deadlineExpired(deadline)) {
+                sourceTruncation = "wall_budget";
+                break;
+            }
+            let summaries;
+            try {
+                summaries = await beforeDeadline(provider.list(request.project_scope_id, { signal: controller.signal }), deadline, controller);
+            }
+            catch (error) {
+                if (!isWallBudgetError(error))
+                    throw error;
+                sourceTruncation = "wall_budget";
+                break;
+            }
+            for (const summary of summaries) {
+                if (deadlineExpired(deadline)) {
+                    controller.abort();
+                    sourceTruncation = "wall_budget";
+                    break providerLoop;
+                }
+                if (summary.project_scope_id !== request.project_scope_id)
+                    continue;
+                if (request.conversation_id && summary.conversation_id !== request.conversation_id)
+                    continue;
+                let snapshot;
+                try {
+                    snapshot = await beforeDeadline(provider.snapshot(request.project_scope_id, summary.conversation_id, {
+                        signal: controller.signal,
+                    }), deadline, controller);
+                }
+                catch (error) {
+                    if (!isWallBudgetError(error))
+                        throw error;
+                    sourceTruncation = "wall_budget";
+                    break providerLoop;
+                }
+                snapshots.push(snapshot);
+                let sequence = 0;
+                const iterator = provider
+                    .stream(request.project_scope_id, summary.conversation_id, {
+                    signal: controller.signal,
+                })[Symbol.asyncIterator]();
+                let iteratorCompleted = false;
+                try {
+                    while (true) {
+                        if (sourceRecords >= request.budgets.max_source_records) {
+                            sourceTruncation = "record_budget";
+                            break;
+                        }
+                        let next;
+                        try {
+                            next = await beforeDeadline(iterator.next(), deadline, controller);
+                        }
+                        catch (error) {
+                            if (!isWallBudgetError(error))
+                                throw error;
+                            sourceTruncation = "wall_budget";
+                            break;
+                        }
+                        if (next.done) {
+                            iteratorCompleted = true;
+                            break;
+                        }
+                        sourceRecords += 1;
+                        sequence += 1;
+                        const native = next.value;
+                        const rawBytes = typeof native.content === "string" ? Buffer.byteLength(native.content) : 0;
+                        if (decodedBytes + rawBytes > request.budgets.max_decoded_bytes) {
+                            sourceTruncation = "byte_budget";
+                            break;
+                        }
+                        if (deadlineExpired(deadline)) {
+                            controller.abort();
+                            sourceTruncation = "wall_budget";
+                            break;
+                        }
+                        const normalized = normalizeConversationRecord({
+                            capabilities: provider.capabilities,
+                            snapshot,
+                            native,
+                            captured_at: snapshot.observed_at,
+                            sequence,
+                        });
+                        decodedBytes += rawBytes;
+                        if (deadlineExpired(deadline)) {
+                            controller.abort();
+                            sourceTruncation = "wall_budget";
+                            break;
+                        }
+                        if (normalized.record)
+                            records.push(normalized.record);
+                    }
+                }
+                finally {
+                    if (!iteratorCompleted)
+                        requestIteratorReturn(iterator);
+                }
+                if (sourceTruncation)
+                    break providerLoop;
+            }
+        }
+    }
+    finally {
+        if (sourceTruncation)
+            controller.abort();
+    }
+    const result = queryConversationRecords(records, snapshots, request, { started_at: started });
+    if (!sourceTruncation || result.truncated)
+        return result;
+    return { ...result, truncated: true, truncation_reason: sourceTruncation };
+}
+class ConversationWallBudgetError extends Error {
+}
+async function beforeDeadline(operation, deadline, controller) {
+    const remaining = deadline - performance.now();
+    if (remaining <= 0) {
+        controller.abort();
+        throw new ConversationWallBudgetError();
+    }
+    let timer;
+    try {
+        const timeout = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => {
+                controller.abort();
+                reject(new ConversationWallBudgetError());
+            }, remaining);
+        });
+        const result = await Promise.race([operation, timeout]);
+        if (deadlineExpired(deadline)) {
+            controller.abort();
+            throw new ConversationWallBudgetError();
+        }
+        return result;
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+function deadlineExpired(deadline) {
+    return performance.now() >= deadline;
+}
+function isWallBudgetError(error) {
+    return error instanceof ConversationWallBudgetError;
+}
+function requestIteratorReturn(iterator) {
+    try {
+        const returned = iterator.return?.();
+        if (returned)
+            void Promise.resolve(returned).catch(() => undefined);
+    }
+    catch {
+        // A provider cleanup failure cannot widen the query budget or replace its reason code.
+    }
+}
+export function queryConversationRecords(inputRecords, snapshots, request, internal = {}) {
+    validateRequest(request);
+    const started = internal.started_at ?? performance.now();
+    const records = [...inputRecords].sort((left, right) => left.project_scope_id.localeCompare(right.project_scope_id) ||
+        left.provider_id.localeCompare(right.provider_id) ||
+        left.conversation_id.localeCompare(right.conversation_id) ||
+        left.sequence - right.sequence ||
+        left.record_id.localeCompare(right.record_id));
+    const regex = request.regex
+        ? compileRegex(request.regex, request.budgets.max_regex_chars)
+        : undefined;
+    const hits = [];
+    let scannedRecords = 0;
+    let decodedBytes = 0;
+    let truncation;
+    for (let index = 0; index < records.length; index += 1) {
+        const record = records[index];
+        if (!structuredMatch(record, request))
+            continue;
+        if (scannedRecords >= request.budgets.max_source_records) {
+            truncation = "record_budget";
+            break;
+        }
+        if (decodedBytes + record.content_bytes > request.budgets.max_decoded_bytes) {
+            truncation = "byte_budget";
+            break;
+        }
+        if (performance.now() - started > request.budgets.max_wall_ms) {
+            truncation = "wall_budget";
+            break;
+        }
+        scannedRecords += 1;
+        decodedBytes += record.content_bytes;
+        if (request.text && !record.content.includes(request.text))
+            continue;
+        if (regex && !regex.test(record.content))
+            continue;
+        if (hits.length >= Math.min(request.limit, request.budgets.max_matches)) {
+            truncation = "match_budget";
+            break;
+        }
+        hits.push({
+            record,
+            citation: citation(record),
+            neighbors: neighbors(records, index, request.context_before ?? 0, request.context_after ?? 0),
+        });
+    }
+    return {
+        schema: "harnery.conversation-query/v1",
+        request,
+        hits,
+        scanned_records: scannedRecords,
+        decoded_bytes: decodedBytes,
+        truncated: truncation !== undefined,
+        ...(truncation ? { truncation_reason: truncation } : {}),
+        snapshots: [...snapshots].sort((left, right) => left.snapshot_id.localeCompare(right.snapshot_id)),
+    };
+}
+export function citation(record) {
+    return {
+        record_id: record.record_id,
+        provider_id: record.provider_id,
+        conversation_id: record.conversation_id,
+        role: record.role,
+        occurred_at: record.occurred_at,
+        native_conversation_id: record.source.native_conversation_id,
+        ...(record.source.native_record_id ? { native_record_id: record.source.native_record_id } : {}),
+        content_digest: record.content_digest,
+    };
+}
+function structuredMatch(record, request) {
+    return (record.project_scope_id === request.project_scope_id &&
+        (!request.provider_id || record.provider_id === request.provider_id) &&
+        (!request.role || record.role === request.role) &&
+        (!request.session_id || record.session_id === request.session_id) &&
+        (!request.conversation_id || record.conversation_id === request.conversation_id) &&
+        (!request.record_id || record.record_id === request.record_id) &&
+        (!request.since || record.occurred_at >= new Date(request.since).toISOString()) &&
+        (!request.until || record.occurred_at <= new Date(request.until).toISOString()));
+}
+function neighbors(records, index, before, after) {
+    const target = records[index];
+    return records
+        .slice(Math.max(0, index - before), index + after + 1)
+        .filter((record) => record.record_id !== target.record_id &&
+        record.project_scope_id === target.project_scope_id &&
+        record.provider_id === target.provider_id &&
+        record.conversation_id === target.conversation_id);
+}
+function compileRegex(pattern, maxChars) {
+    if (pattern.length === 0 || pattern.length > maxChars)
+        throw new Error("conversation regex limit");
+    if (/\([^)]*[+*][^)]*\)[+*{]/.test(pattern))
+        throw new Error("unsafe nested conversation regex");
+    return new RegExp(pattern, "iu");
+}
+function validateRequest(request) {
+    if (!request.project_scope_id)
+        throw new Error("conversation query requires project_scope_id");
+    for (const [field, value] of Object.entries({ limit: request.limit, ...request.budgets })) {
+        if (!Number.isSafeInteger(value) || value <= 0)
+            throw new Error(`invalid conversation ${field}`);
+    }
+    if (request.role && request.role !== "user" && request.role !== "assistant") {
+        throw new Error("excluded conversation role");
+    }
+    if (request.text && request.regex)
+        throw new Error("conversation query accepts text or regex, not both");
+}

package/dist/core/conversations/search-index.d.ts

@@ -0,0 +1,9 @@
+import type { HarneryConversationRecordV1 } from "./contract.js";
+export interface HarneryConversationSearchIndexV1 {
+    schema: "harnery.conversation-search-index/v1";
+    source_digest: `sha256:${string}`;
+    terms: Readonly<Record<string, readonly string[]>>;
+}
+export declare function buildConversationSearchIndex(records: readonly HarneryConversationRecordV1[]): HarneryConversationSearchIndexV1;
+export declare function verifyIndexedRecords(index: HarneryConversationSearchIndexV1, records: readonly HarneryConversationRecordV1[], term: string): HarneryConversationRecordV1[];
+//# sourceMappingURL=search-index.d.ts.map

package/dist/core/conversations/search-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-index.d.ts","sourceRoot":"","sources":["../../../src/core/conversations/search-index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AAGjE,MAAM,WAAW,gCAAgC;IAC/C,MAAM,EAAE,sCAAsC,CAAC;IAC/C,aAAa,EAAE,UAAU,MAAM,EAAE,CAAC;IAClC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;CACpD;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,SAAS,2BAA2B,EAAE,GAC9C,gCAAgC,CAqBlC;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,gCAAgC,EACvC,OAAO,EAAE,SAAS,2BAA2B,EAAE,EAC/C,IAAI,EAAE,MAAM,GACX,2BAA2B,EAAE,CAS/B"}

package/dist/core/conversations/search-index.js

@@ -0,0 +1,29 @@
+import { digest } from "./normalize.js";
+export function buildConversationSearchIndex(records) {
+    const terms = new Map();
+    const ordered = [...records].sort((left, right) => left.record_id.localeCompare(right.record_id));
+    for (const record of ordered) {
+        for (const term of record.content.toLocaleLowerCase().match(/[\p{L}\p{N}_-]{2,}/gu) ?? []) {
+            const ids = terms.get(term) ?? new Set();
+            ids.add(record.record_id);
+            terms.set(term, ids);
+        }
+    }
+    return {
+        schema: "harnery.conversation-search-index/v1",
+        source_digest: digest(ordered.map((record) => `${record.record_id}:${record.content_digest}`).join("\n")),
+        terms: Object.fromEntries([...terms]
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([term, ids]) => [term, [...ids].sort()])),
+    };
+}
+export function verifyIndexedRecords(index, records, term) {
+    const byId = new Map(records.map((record) => [record.record_id, record]));
+    return (index.terms[term.toLocaleLowerCase()] ?? []).map((id) => {
+        const record = byId.get(id);
+        if (!record?.content.toLocaleLowerCase().includes(term.toLocaleLowerCase())) {
+            throw new Error(`stale conversation index hit: ${id}`);
+        }
+        return record;
+    });
+}

package/dist/core/diagnostics/advice.d.ts

@@ -0,0 +1,9 @@
+import type { SupervisorCapability, SupervisorFinding } from "../supervisor/contract.js";
+import { type DiagnosticAdvice } from "./contract.js";
+export interface BuildDiagnosticAdviceInput {
+    findings: readonly SupervisorFinding[];
+    sourceCapability: SupervisorCapability;
+    evaluatedAt: string;
+}
+export declare function buildDiagnosticAdvice(input: BuildDiagnosticAdviceInput): DiagnosticAdvice;
+//# sourceMappingURL=advice.d.ts.map

package/dist/core/diagnostics/advice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advice.d.ts","sourceRoot":"","sources":["../../../src/core/diagnostics/advice.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACzF,OAAO,EAGL,KAAK,gBAAgB,EAGtB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACvC,gBAAgB,EAAE,oBAAoB,CAAC;IACvC,WAAW,EAAE,MAAM,CAAC;CACrB;AAQD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,0BAA0B,GAAG,gBAAgB,CA4CzF"}

package/dist/core/diagnostics/advice.js

@@ -0,0 +1,112 @@
+import { DIAGNOSTIC_ADVICE_LIMITS, DIAGNOSTIC_ADVICE_SCHEMA_VERSION, } from "./contract.js";
+const SEVERITY_RANK = {
+    info: 0,
+    warning: 1,
+    critical: 2,
+};
+export function buildDiagnosticAdvice(input) {
+    const sourceAvailable = input.sourceCapability.state === "supported";
+    const active = sourceAvailable
+        ? input.findings.filter((finding) => finding.state === "opened").sort(compareFindings)
+        : [];
+    const pressureFindings = active.filter((finding) => finding.severity === "warning" || finding.severity === "critical");
+    const critical = pressureFindings.filter((finding) => finding.severity === "critical");
+    const warning = pressureFindings.filter((finding) => finding.severity === "warning");
+    const pressure = critical.length
+        ? "critical"
+        : warning.length
+            ? "elevated"
+            : sourceAvailable
+                ? "normal"
+                : "unknown";
+    const fanOutRecommendation = pressure === "critical"
+        ? "avoid-new-fan-out"
+        : pressure === "elevated"
+            ? "use-caution"
+            : pressure === "normal"
+                ? "proceed"
+                : "unknown";
+    const contributing = pressureFindings.slice(0, DIAGNOSTIC_ADVICE_LIMITS.max_contributing_findings);
+    return {
+        schema_version: DIAGNOSTIC_ADVICE_SCHEMA_VERSION,
+        evaluated_at: input.evaluatedAt,
+        pressure,
+        fan_out_recommendation: fanOutRecommendation,
+        observer_only: true,
+        summary: summaryFor(pressure),
+        source_capability: input.sourceCapability,
+        active_finding_count: active.length,
+        contributing_finding_count: pressureFindings.length,
+        omitted_contributing_finding_count: Math.max(0, pressureFindings.length - contributing.length),
+        contributing_findings: contributing.map(adviceFinding),
+        reasons: reasonsFor(critical, warning, input.sourceCapability),
+    };
+}
+function adviceFinding(finding) {
+    return {
+        finding_id: finding.id,
+        finding_kind: finding.finding_kind,
+        severity: finding.severity,
+        summary: finding.summary,
+        scope_kind: finding.scope_kind,
+        scope_id: finding.scope_id,
+        occurrence_count: finding.occurrence_count,
+        owner_kind: finding.attribution?.owner_kind,
+        owner_id: finding.attribution?.owner_id,
+        workload_relationship: finding.workload_context?.relationship,
+    };
+}
+function reasonsFor(critical, warning, capability) {
+    const reasons = [];
+    if (critical.length) {
+        reasons.push({
+            code: "critical_findings_active",
+            summary: `${critical.length} active critical finding${critical.length === 1 ? "" : "s"} ${critical.length === 1 ? "requires" : "require"} attention.`,
+            finding_ids: boundedIds(critical),
+        });
+    }
+    if (warning.length) {
+        reasons.push({
+            code: "warning_findings_active",
+            summary: `${warning.length} active warning finding${warning.length === 1 ? "" : "s"} ${warning.length === 1 ? "indicates" : "indicate"} elevated pressure.`,
+            finding_ids: boundedIds(warning),
+        });
+    }
+    if (capability.state !== "supported") {
+        reasons.push({
+            code: "findings_source_unavailable",
+            summary: `The findings source is ${capability.state}${capability.reason_code ? ` (${capability.reason_code})` : ""}.`,
+            finding_ids: [],
+        });
+    }
+    if (!critical.length && !warning.length && capability.state === "supported") {
+        reasons.push({
+            code: "no_active_pressure_findings",
+            summary: "No active warning or critical findings were observed.",
+            finding_ids: [],
+        });
+    }
+    return reasons.slice(0, DIAGNOSTIC_ADVICE_LIMITS.max_reasons);
+}
+function boundedIds(findings) {
+    return findings
+        .slice(0, DIAGNOSTIC_ADVICE_LIMITS.max_contributing_findings)
+        .map((finding) => finding.id);
+}
+function summaryFor(pressure) {
+    switch (pressure) {
+        case "critical":
+            return "Critical local pressure is active. Avoid starting additional agent work until the findings change.";
+        case "elevated":
+            return "Elevated local pressure is active. Limit new fan-out and inspect the contributing findings.";
+        case "normal":
+            return "No active warning or critical findings were observed. Diagnostics do not restrict new fan-out.";
+        case "unknown":
+            return "Local pressure cannot be determined because the findings source is unavailable.";
+    }
+}
+function compareFindings(left, right) {
+    return (SEVERITY_RANK[right.severity] - SEVERITY_RANK[left.severity] ||
+        right.observed_at.localeCompare(left.observed_at) ||
+        left.id.localeCompare(right.id));
+}

package/dist/core/diagnostics/bundle.d.ts

@@ -0,0 +1,35 @@
+import type { ArtifactActor, ArtifactInventoryEntry } from "../artifacts/index.js";
+import { type DiagnosticBundleManifest, type DiagnosticReplayResult, type DiagnosticSummary, type ValidatedDiagnosticBundle } from "./contract.js";
+export interface CaptureDiagnosticBundleInput {
+    findingId?: string;
+    startAt?: string;
+    endAt?: string;
+    actor?: ArtifactActor;
+    retentionDays?: number;
+    now?: Date;
+    machineLabel?: string;
+    engineVersion?: string;
+}
+export interface CapturedDiagnosticBundle {
+    path: string;
+    manifest: DiagnosticBundleManifest;
+    summary: DiagnosticSummary;
+}
+export interface DiagnosticBundleListRow {
+    artifact_id: string;
+    created_at: string;
+    expires_at: string | null;
+    classification: ArtifactInventoryEntry["classification"];
+    valid: boolean;
+    captured_at?: string;
+    finding_id?: string;
+    error?: string;
+}
+export declare function captureDiagnosticBundle(repoRootRaw: string, input?: CaptureDiagnosticBundleInput): CapturedDiagnosticBundle;
+export declare function validateDiagnosticBundle(repoRootRaw: string, ref: string): ValidatedDiagnosticBundle;
+/** Frozen web readers accept an opaque artifact id, never a filesystem path. */
+export declare function readFrozenDiagnosticBundle(repoRoot: string, artifactId: string): ValidatedDiagnosticBundle;
+export declare function showDiagnosticBundle(repoRoot: string, ref: string): ValidatedDiagnosticBundle;
+export declare function listDiagnosticBundles(repoRoot: string): DiagnosticBundleListRow[];
+export declare function replayDiagnosticBundle(repoRoot: string, ref: string, now?: Date): DiagnosticReplayResult;
+//# sourceMappingURL=bundle.d.ts.map

package/dist/core/diagnostics/bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../../src/core/diagnostics/bundle.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAwBnF,OAAO,EAUL,KAAK,wBAAwB,EAG7B,KAAK,sBAAsB,EAE3B,KAAK,iBAAiB,EAEtB,KAAK,yBAAyB,EAC/B,MAAM,eAAe,CAAC;AA0BvB,MAAM,WAAW,4BAA4B;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,wBAAwB,CAAC;IACnC,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAED,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,EAAE,sBAAsB,CAAC,gBAAgB,CAAC,CAAC;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,KAAK,GAAE,4BAAiC,GACvC,wBAAwB,CAqG1B;AAED,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,GACV,yBAAyB,CA+C3B;AAED,gFAAgF;AAChF,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,yBAAyB,CAK3B;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,yBAAyB,CAE7F;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,uBAAuB,EAAE,CA0BjF;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,OAAa,GACf,sBAAsB,CAgBxB"}