@wirecat/cli-core 0.344.0 → 0.345.0

package/dist/meetings/mcp/index.d.ts

@@ -38,6 +38,7 @@ export declare const meetingTools: ({
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -53,11 +54,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -75,11 +76,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -101,7 +102,6 @@ export declare const meetingTools: ({
                 minimum: number;
             };
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
@@ -188,6 +188,7 @@ export declare const meetingTools: ({
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -203,11 +204,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -225,11 +226,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -251,7 +252,6 @@ export declare const meetingTools: ({
                 minimum: number;
             };
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
@@ -338,6 +338,7 @@ export declare const meetingTools: ({
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -353,11 +354,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -375,11 +376,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -401,7 +402,6 @@ export declare const meetingTools: ({
                 minimum: number;
             };
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
@@ -488,6 +488,7 @@ export declare const meetingTools: ({
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -503,11 +504,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -525,11 +526,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -551,7 +552,6 @@ export declare const meetingTools: ({
                 minimum: number;
             };
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
@@ -638,6 +638,7 @@ export declare const meetingTools: ({
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -653,11 +654,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -675,11 +676,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -701,7 +702,6 @@ export declare const meetingTools: ({
                 minimum: number;
             };
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;

package/dist/services/index.d.ts

@@ -2,6 +2,9 @@ import { type BotCheckService } from "../botcheck/service.js";
 export type { ContextEvidenceItem, ContextEvidencePage, ContextEvidenceReader, ContextEvidenceRequest, ContextReadLimits, ContextReadUsage, ContextSource, ScopedContextEvidenceReader, } from "./context-evidence.js";
 export { createContextEvidenceReader } from "./context-evidence.js";
 export { type DownloadedModel, downloadImageModel, downloadTextModel, type ModelDownloadOptions, } from "./model-downloads.js";
+export type { ProjectEvidenceItem, ProjectGathering, ProjectGatheringPorts, ProjectGatheringStop, ProjectSourceFetcher, } from "./project-gathering.js";
+export { gatherProjectEvidence } from "./project-gathering.js";
+export type { ProjectGatheringBudgets, ProjectGatheringRequest, ProjectLane, ProjectLaneKind, } from "./project-gathering-request.js";
 import { type AccountService } from "./account.js";
 import { type AdminService } from "./admin.js";
 import { type AdminStatisticsService } from "./admin-statistics.js";

package/dist/services/index.js

@@ -1,6 +1,7 @@
 import { botCheckService } from "../botcheck/service.js";
 export { createContextEvidenceReader } from "./context-evidence.js";
 export { downloadImageModel, downloadTextModel, } from "./model-downloads.js";
+export { gatherProjectEvidence } from "./project-gathering.js";
 import { accountService } from "./account.js";
 import { adminService } from "./admin.js";
 import { adminStatisticsService } from "./admin-statistics.js";

package/dist/services/project-gathering-request.d.ts

@@ -0,0 +1,120 @@
+import { type ContextSource } from "../context/evidence.js";
+export interface ProjectGatheringRequest {
+    project: {
+        name: string;
+        background?: string;
+        aliases?: string[];
+    };
+    keywords?: string[];
+    people?: {
+        name: string;
+        reference?: string;
+    }[];
+    sources: ContextSource[];
+    scope: "explicit" | "all-connected";
+    lookbackDays?: number;
+    after?: number;
+    before?: number;
+    asOf?: number;
+    fetch?: "none" | "before-read";
+    budgets?: ProjectGatheringBudgets;
+    runKey?: string;
+    checkpoint?: string;
+    signal?: AbortSignal;
+}
+export interface ProjectGatheringBudgets {
+    maxReads?: number;
+    maxReadBytes?: number;
+    maxPageBytes?: number;
+    maxElapsedMs?: number;
+    maxItems?: number;
+}
+export type ProjectLaneKind = "project" | "alias" | "keyword" | "person";
+export interface ProjectLane {
+    id: string;
+    kinds: ProjectLaneKind[];
+    query: string;
+    people: string[];
+}
+export type ProjectUnitState = "pending" | "partial" | "done" | "unavailable" | "failed" | "read-limited";
+export interface ProjectUnitProgress {
+    state: ProjectUnitState;
+    pages: number;
+    cursor: {
+        at: number;
+        id: number;
+        scope: string;
+    } | null;
+    code: string | null;
+}
+export type ProjectFetchState = "fetched" | "unsupported" | "failed" | "not-requested";
+export interface ProjectGatheringCheckpoint {
+    version: 1;
+    runKey: string;
+    fingerprint: string;
+    after: number;
+    before: number;
+    asOf: number;
+    fetched: {
+        state: ProjectFetchState;
+        history: "complete" | "partial" | "unknown" | null;
+        code: string | null;
+    }[];
+    units: ProjectUnitProgress[];
+    seen: string[];
+    totals: {
+        reads: number;
+        readBytes: number;
+        items: number;
+        invocations: number;
+    };
+}
+export declare const CONTEXT_CHUNK_DAYS = 90;
+export declare const projectGatheringRequest: (input: ProjectGatheringRequest, now: number) => {
+    project: {
+        name: string;
+        background: string | null;
+        aliases: string[];
+    };
+    keywords: string[];
+    people: {
+        name: string;
+        reference: string | null;
+    }[];
+    lanes: ProjectLane[];
+    sources: ContextSource[];
+    scope: "all-connected" | "explicit";
+    lookbackDays: number | null;
+    window: {
+        after: number;
+        before: number;
+        asOf: number;
+    };
+    fetch: "before-read" | "none";
+    budgets: Required<ProjectGatheringBudgets>;
+    fingerprint: string;
+    runKey: string;
+    checkpoint: string | undefined;
+    signal: AbortSignal | undefined;
+};
+export type ProjectGatheringPlan = ReturnType<typeof projectGatheringRequest>;
+/** Newest chunk first, so a cut budget keeps the most recent evidence of every lane. */
+export declare const contextChunks: (after: number, before: number) => {
+    after: number;
+    before: number;
+}[];
+export declare const projectUnits: (plan: ProjectGatheringPlan, window: {
+    after: number;
+    before: number;
+}) => {
+    lane: ProjectLane;
+    source: ContextSource;
+    sourceIndex: number;
+    chunk: {
+        after: number;
+        before: number;
+    };
+}[];
+export declare const seenKey: (ref: string) => string;
+export declare const encodeCheckpoint: (checkpoint: ProjectGatheringCheckpoint) => string;
+export declare const decodeCheckpoint: (text: string, plan: ProjectGatheringPlan) => ProjectGatheringCheckpoint;

package/dist/services/project-gathering-request.js

@@ -0,0 +1,217 @@
+import { createHash } from "node:crypto";
+import { CliError } from "@wirecat/cli-base";
+import { contextSource } from "../context/evidence.js";
+import { contextSourceKey } from "../context/evidence-response.js";
+const DAY = 86400000;
+const MAX_TIME = 8_640_000_000_000_000;
+export const CONTEXT_CHUNK_DAYS = 90;
+const LIMITS = { lanes: 16, sources: 32, units: 512, lookbackDays: 730, people: 16 };
+const BUDGETS = {
+    maxReads: [48, 512],
+    maxReadBytes: [2097152, 16777216],
+    maxPageBytes: [65536, 262144],
+    maxElapsedMs: [60000, 600000],
+    maxItems: [100, 500],
+};
+const fail = (message, param) => {
+    throw new CliError("validation_error", message, param ? { param } : undefined);
+};
+const known = (value, allowed, prefix) => {
+    const unknown = Object.keys(value).find((key) => !allowed.includes(key));
+    if (unknown)
+        fail(`${prefix}${unknown} is not supported`, `${prefix}${unknown}`);
+};
+const text = (value, name, max) => typeof value === "string" && value.trim() && Buffer.byteLength(value) <= max
+    ? value.trim()
+    : fail(`${name} needs 1–${max} UTF-8 bytes`, name);
+const whole = (value, name, low, high) => Number.isSafeInteger(value) && value >= low && value <= high
+    ? value
+    : fail(`${name} must be a whole number from ${low} to ${high}`, name);
+const laneQuery = (value, name) => {
+    const query = text(value, name, 2048);
+    const words = query.match(/[\p{L}\p{N}]+/gu) ?? [];
+    if (!words.length || words.length > 16)
+        fail(`${name} needs 1–16 literal words`, name);
+    return words.join(" ");
+};
+const list = (value, name, max) => {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > max)
+        return fail(`${name} needs at most ${max} entries`, name);
+    return value;
+};
+export const projectGatheringRequest = (input, now) => {
+    if (!input || typeof input !== "object")
+        fail("request needs a project and sources");
+    known(input, [
+        "project",
+        "keywords",
+        "people",
+        "sources",
+        "scope",
+        "lookbackDays",
+        "after",
+        "before",
+        "asOf",
+        "fetch",
+        "budgets",
+        "runKey",
+        "checkpoint",
+        "signal",
+    ], "");
+    if (!input.project || typeof input.project !== "object")
+        fail("project needs a name", "project");
+    known(input.project, ["name", "background", "aliases"], "project.");
+    const project = {
+        name: text(input.project.name, "project.name", 512),
+        background: input.project.background === undefined ? null : text(input.project.background, "project.background", 8192),
+        aliases: list(input.project.aliases, "project.aliases", LIMITS.lanes).map((a, i) => text(a, `project.aliases.${i}`, 512)),
+    };
+    const keywords = list(input.keywords, "keywords", LIMITS.lanes).map((k, i) => laneQuery(k, `keywords.${i}`));
+    const people = list(input.people, "people", LIMITS.people).map((person, i) => {
+        if (!person || typeof person !== "object")
+            return fail(`people.${i} needs a name`, `people.${i}`);
+        known(person, ["name", "reference"], `people.${i}.`);
+        const p = person;
+        return {
+            name: laneQuery(p.name, `people.${i}.name`),
+            reference: p.reference === undefined ? null : text(p.reference, `people.${i}.reference`, 1024),
+        };
+    });
+    if (input.scope !== "explicit" && input.scope !== "all-connected")
+        fail("scope must be explicit or all-connected; omitted scope never means every account", "scope");
+    const sourceList = list(input.sources, "sources", LIMITS.sources);
+    if (!sourceList.length)
+        fail("sources needs at least one resolved source; omitted scope never means every account", "sources");
+    const sources = sourceList.map((s) => contextSource(s));
+    if (new Set(sources.map(contextSourceKey)).size !== sources.length)
+        fail("sources lists one source twice", "sources");
+    const lanes = [];
+    const lane = (kind, query, person) => {
+        const key = query.toLowerCase();
+        const found = lanes.find((l) => l.query.toLowerCase() === key) ?? {
+            id: `l${lanes.length + 1}`,
+            kinds: [],
+            query,
+            people: [],
+        };
+        if (!lanes.includes(found))
+            lanes.push(found);
+        if (!found.kinds.includes(kind))
+            found.kinds.push(kind);
+        if (person && !found.people.includes(person))
+            found.people.push(person);
+    };
+    lane("project", laneQuery(project.name, "project.name"));
+    for (const [i, a] of project.aliases.entries())
+        lane("alias", laneQuery(a, `project.aliases.${i}`));
+    for (const k of keywords)
+        lane("keyword", k);
+    for (const p of people)
+        lane("person", p.name, p.reference ?? p.name);
+    if (lanes.length > LIMITS.lanes)
+        fail(`at most ${LIMITS.lanes} distinct search lanes`, "keywords");
+    const fetch = input.fetch ?? "none";
+    if (fetch !== "none" && fetch !== "before-read")
+        fail("fetch must be none or before-read", "fetch");
+    const explicit = input.after !== undefined || input.before !== undefined;
+    if (explicit && input.lookbackDays !== undefined)
+        fail("give lookbackDays or after/before, not both", "lookbackDays");
+    if (explicit && (input.after === undefined || input.before === undefined))
+        fail("an explicit window needs both after and before", input.after === undefined ? "after" : "before");
+    const asOf = input.asOf === undefined ? null : whole(input.asOf, "asOf", 1, MAX_TIME);
+    const lookbackDays = explicit ? null : whole(input.lookbackDays ?? 60, "lookbackDays", 1, LIMITS.lookbackDays);
+    const window = explicit
+        ? (() => {
+            const after = whole(input.after, "after", 0, MAX_TIME);
+            const before = whole(input.before, "before", after + 1, MAX_TIME);
+            if (before - after > LIMITS.lookbackDays * DAY)
+                fail(`window must not exceed ${LIMITS.lookbackDays} days`, "after");
+            return { after, before, asOf: asOf ?? before };
+        })()
+        : { after: Math.max(0, (asOf ?? now) - lookbackDays * DAY), before: asOf ?? now, asOf: asOf ?? now };
+    if (input.budgets !== undefined && (!input.budgets || typeof input.budgets !== "object"))
+        fail("budgets needs whole-run limits", "budgets");
+    const given = input.budgets ?? {};
+    known(given, Object.keys(BUDGETS), "budgets.");
+    const budgets = Object.fromEntries(Object.entries(BUDGETS).map(([key, [fallback, max]]) => [
+        key,
+        whole(given[key] ?? fallback, `budgets.${key}`, 1, max),
+    ]));
+    if (budgets.maxPageBytes > budgets.maxReadBytes)
+        budgets.maxPageBytes = budgets.maxReadBytes;
+    const fingerprint = createHash("sha256")
+        .update(JSON.stringify([
+        "project-gathering-v1",
+        project,
+        lanes,
+        people,
+        sources.map(contextSourceKey),
+        input.scope,
+        lookbackDays,
+        explicit ? [window.after, window.before] : null,
+        asOf,
+        fetch,
+    ]))
+        .digest("hex");
+    const runKey = input.runKey === undefined ? fingerprint : text(input.runKey, "runKey", 256);
+    if (input.checkpoint !== undefined && typeof input.checkpoint !== "string")
+        fail("checkpoint must be text", "checkpoint");
+    return {
+        project,
+        keywords,
+        people,
+        lanes,
+        sources,
+        scope: input.scope,
+        lookbackDays,
+        window,
+        fetch,
+        budgets,
+        fingerprint,
+        runKey,
+        checkpoint: input.checkpoint,
+        signal: input.signal,
+    };
+};
+/** Newest chunk first, so a cut budget keeps the most recent evidence of every lane. */
+export const contextChunks = (after, before) => {
+    const chunks = [];
+    for (let end = before; end > after; end -= CONTEXT_CHUNK_DAYS * DAY)
+        chunks.push({ after: Math.max(after, end - CONTEXT_CHUNK_DAYS * DAY), before: end });
+    return chunks;
+};
+export const projectUnits = (plan, window) => {
+    const units = contextChunks(window.after, window.before).flatMap((chunk) => plan.lanes.flatMap((lane) => plan.sources.map((source, sourceIndex) => ({ lane, source, sourceIndex, chunk }))));
+    if (units.length > LIMITS.units)
+        fail(`${units.length} lane × source × 90-day reads exceed ${LIMITS.units}; narrow the lanes, sources or window`);
+    return units;
+};
+export const seenKey = (ref) => createHash("sha256").update(ref).digest("base64url").slice(0, 16);
+export const encodeCheckpoint = (checkpoint) => Buffer.from(JSON.stringify(checkpoint)).toString("base64url");
+export const decodeCheckpoint = (text, plan) => {
+    let value;
+    try {
+        if (!/^[A-Za-z0-9_-]{1,1048576}$/.test(text))
+            throw Error();
+        value = JSON.parse(Buffer.from(text, "base64url").toString("utf8"));
+    }
+    catch {
+        return fail("invalid project gathering checkpoint", "checkpoint");
+    }
+    if (value?.version !== 1 ||
+        !Array.isArray(value.units) ||
+        !Array.isArray(value.fetched) ||
+        !Array.isArray(value.seen) ||
+        !Number.isSafeInteger(value.after) ||
+        !Number.isSafeInteger(value.before) ||
+        value.after < 0 ||
+        value.before <= value.after)
+        fail("invalid project gathering checkpoint", "checkpoint");
+    if (value.runKey !== plan.runKey)
+        fail("checkpoint belongs to another run key", "checkpoint");
+    if (value.fingerprint !== plan.fingerprint)
+        fail("this run key was started with another request; a resumed run keeps its project, lanes, sources and window", "checkpoint");
+    return value;
+};

package/dist/services/project-gathering.d.ts

@@ -0,0 +1,89 @@
+import type { ContextEvidenceItem, ContextEvidenceReader, ContextSource } from "../context/evidence.js";
+import { type ProjectFetchState, type ProjectGatheringRequest, type ProjectLane } from "./project-gathering-request.js";
+/** A connector's history fetch into the store; the store reads that follow find what it saved. */
+export interface ProjectSourceFetcher {
+    fetch(request: {
+        source: ContextSource;
+        after: number;
+        before: number;
+        signal?: AbortSignal;
+    }): Promise<{
+        status: "fetched" | "unsupported";
+        history: "complete" | "partial" | "unknown";
+    }>;
+}
+export interface ProjectGatheringPorts {
+    evidence: ContextEvidenceReader;
+    fetcher?: ProjectSourceFetcher;
+    now?: () => number;
+}
+export interface ProjectEvidenceItem extends Omit<ContextEvidenceItem, "text"> {
+    kind: ContextSource["kind"];
+    source: number;
+    text: string;
+    textTruncated: boolean;
+    lanes: string[];
+    context: "project" | "person-only";
+}
+export type ProjectGatheringStop = "reads" | "read-bytes" | "elapsed" | "items" | null;
+export declare const gatherProjectEvidence: (ports: ProjectGatheringPorts, request: ProjectGatheringRequest) => Promise<{
+    schemaVersion: 1;
+    runKey: string;
+    fingerprint: string;
+    resumed: boolean;
+    project: {
+        name: string;
+        background: string | null;
+        aliases: string[];
+    };
+    window: {
+        after: number;
+        before: number;
+        asOf: number;
+        lookbackDays: number | null;
+        basis: "explicit" | "lookback";
+        timeBasis: "per-item-time-kind";
+    };
+    scope: {
+        origin: "all-connected" | "explicit";
+        sources: ContextSource[];
+    };
+    lanes: ProjectLane[];
+    fetch: {
+        state: ProjectFetchState;
+        history: "complete" | "partial" | "unknown" | null;
+        code: string | null;
+        source: number;
+    }[];
+    units: {
+        lane: string;
+        source: number;
+        after: number;
+        before: number;
+        state: import("./project-gathering-request.js").ProjectUnitState;
+        pages: number;
+        issue: string | null;
+    }[];
+    items: ProjectEvidenceItem[];
+    matchedAgain: {
+        ref: string;
+        lanes: string[];
+    }[];
+    usage: {
+        reads: number;
+        readBytes: number;
+        items: number;
+        elapsedMs: number;
+    };
+    totals: {
+        reads: number;
+        readBytes: number;
+        items: number;
+        invocations: number;
+    };
+    stopped: ProjectGatheringStop;
+    complete: boolean;
+    completeness: "unknown";
+    checkpoint: string | null;
+}>;
+export type ProjectGathering = Awaited<ReturnType<typeof gatherProjectEvidence>>;