@mandipadk7/kavi 0.1.7 → 1.0.0

package/dist/recommendations.js

@@ -1,5 +1,6 @@
 import { buildClaimHotspots } from "./decision-ledger.js";
 import { findOwnershipRuleConflicts } from "./ownership.js";
+import { nowIso } from "./paths.js";
 function normalizePath(value) {
     return value.trim().replaceAll("\\", "/").replace(/^\.\/+/, "").replace(/\/+$/, "");
 }
@@ -11,7 +12,100 @@ function pathMatchesScope(scope, filePath) {
 function otherAgent(agent) {
     return agent === "codex" ? "claude" : "codex";
 }
-export function buildOperatorRecommendations(session) {
+function stableSerialize(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((item)=>stableSerialize(item)).join(",")}]`;
+    }
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value).sort(([left], [right])=>left.localeCompare(right)).map(([key, item])=>`${JSON.stringify(key)}:${stableSerialize(item)}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function recommendationFingerprint(draft) {
+    return stableSerialize({
+        id: draft.id,
+        kind: draft.kind,
+        title: draft.title,
+        detail: draft.detail,
+        targetAgent: draft.targetAgent,
+        filePath: draft.filePath,
+        taskIds: [
+            ...draft.taskIds
+        ].sort(),
+        reviewNoteIds: [
+            ...draft.reviewNoteIds
+        ].sort(),
+        metadata: draft.metadata
+    });
+}
+function recommendationPriority(kind) {
+    switch(kind){
+        case "integration":
+            return 0;
+        case "handoff":
+            return 1;
+        case "ownership-config":
+            return 2;
+        default:
+            return 3;
+    }
+}
+function recommendationToneSort(left, right) {
+    const statusDelta = Number(left.status === "dismissed") - Number(right.status === "dismissed");
+    if (statusDelta !== 0) {
+        return statusDelta;
+    }
+    const followUpDelta = Number(right.openFollowUpTaskIds.length > 0) - Number(left.openFollowUpTaskIds.length > 0);
+    if (followUpDelta !== 0) {
+        return followUpDelta;
+    }
+    const kindDelta = recommendationPriority(left.kind) - recommendationPriority(right.kind);
+    if (kindDelta !== 0) {
+        return kindDelta;
+    }
+    return left.title.localeCompare(right.title);
+}
+function recommendationStateFor(session, draft) {
+    return (session.recommendationStates ?? []).find((state)=>state.id === draft.id) ?? null;
+}
+function recommendationOpenFollowUpTaskIds(session, appliedTaskIds) {
+    return appliedTaskIds.filter((taskId)=>session.tasks.some((task)=>task.id === taskId && (task.status === "pending" || task.status === "running" || task.status === "blocked")));
+}
+function hydrateRecommendation(session, draft) {
+    const fingerprint = recommendationFingerprint(draft);
+    const persisted = recommendationStateFor(session, draft);
+    const dismissedStillMatches = persisted?.status === "dismissed" && persisted.fingerprint === fingerprint;
+    const status = dismissedStillMatches ? "dismissed" : "active";
+    const appliedTaskIds = persisted?.appliedTaskIds ?? [];
+    const openFollowUpTaskIds = recommendationOpenFollowUpTaskIds(session, appliedTaskIds);
+    return {
+        ...draft,
+        fingerprint,
+        status,
+        dismissedReason: status === "dismissed" ? persisted?.dismissedReason ?? null : null,
+        dismissedAt: status === "dismissed" ? persisted?.dismissedAt ?? null : null,
+        lastAppliedAt: persisted?.lastAppliedAt ?? null,
+        appliedTaskIds,
+        openFollowUpTaskIds
+    };
+}
+function recommendationMatchesQuery(recommendation, query) {
+    const includeDismissed = query.includeDismissed ?? false;
+    if (!includeDismissed && recommendation.status === "dismissed") {
+        return false;
+    }
+    if (query.kind && query.kind !== "all" && recommendation.kind !== query.kind) {
+        return false;
+    }
+    if (query.targetAgent && query.targetAgent !== "all" && recommendation.targetAgent !== query.targetAgent) {
+        return false;
+    }
+    if (query.status && query.status !== "all" && recommendation.status !== query.status) {
+        return false;
+    }
+    return true;
+}
+function buildRecommendationDrafts(session) {
     const recommendations = [];
     const hotspots = buildClaimHotspots(session);
     const ownershipConflicts = findOwnershipRuleConflicts(session.config);
@@ -112,27 +206,119 @@ export function buildOperatorRecommendations(session) {
             deduped.set(recommendation.id, recommendation);
         }
     }
-    const priority = (kind)=>{
-        switch(kind){
-            case "integration":
-                return 0;
-            case "handoff":
-                return 1;
-            case "ownership-config":
-                return 2;
-            default:
-                return 3;
-        }
-    };
     return [
         ...deduped.values()
-    ].sort((left, right)=>{
-        const kindDelta = priority(left.kind) - priority(right.kind);
-        if (kindDelta !== 0) {
-            return kindDelta;
-        }
-        return left.title.localeCompare(right.title);
+    ];
+}
+export function buildOperatorRecommendations(session, query = {}) {
+    return buildRecommendationDrafts(session).map((draft)=>hydrateRecommendation(session, draft)).filter((recommendation)=>recommendationMatchesQuery(recommendation, query)).sort(recommendationToneSort);
+}
+export function findOperatorRecommendation(session, recommendationId) {
+    return buildOperatorRecommendations(session, {
+        includeDismissed: true
+    }).find((recommendation)=>recommendation.id === recommendationId) ?? null;
+}
+function upsertRecommendationState(session, nextState) {
+    session.recommendationStates = [
+        ...(session.recommendationStates ?? []).filter((state)=>state.id !== nextState.id),
+        nextState
+    ].sort((left, right)=>left.id.localeCompare(right.id));
+    return nextState;
+}
+export function dismissOperatorRecommendation(session, recommendationId, reason) {
+    const recommendation = findOperatorRecommendation(session, recommendationId);
+    if (!recommendation) {
+        throw new Error(`Recommendation ${recommendationId} was not found.`);
+    }
+    const timestamp = nowIso();
+    upsertRecommendationState(session, {
+        id: recommendation.id,
+        fingerprint: recommendation.fingerprint,
+        status: "dismissed",
+        dismissedReason: reason,
+        dismissedAt: timestamp,
+        lastAppliedAt: recommendation.lastAppliedAt,
+        appliedTaskIds: recommendation.appliedTaskIds,
+        updatedAt: timestamp
+    });
+    return findOperatorRecommendation(session, recommendationId) ?? recommendation;
+}
+export function restoreOperatorRecommendation(session, recommendationId) {
+    const recommendation = findOperatorRecommendation(session, recommendationId);
+    if (!recommendation) {
+        throw new Error(`Recommendation ${recommendationId} was not found.`);
+    }
+    const timestamp = nowIso();
+    upsertRecommendationState(session, {
+        id: recommendation.id,
+        fingerprint: recommendation.fingerprint,
+        status: "active",
+        dismissedReason: null,
+        dismissedAt: null,
+        lastAppliedAt: recommendation.lastAppliedAt,
+        appliedTaskIds: recommendation.appliedTaskIds,
+        updatedAt: timestamp
     });
+    return findOperatorRecommendation(session, recommendationId) ?? recommendation;
+}
+export function recordRecommendationApplied(session, recommendationId, taskId) {
+    const recommendation = findOperatorRecommendation(session, recommendationId);
+    if (!recommendation) {
+        throw new Error(`Recommendation ${recommendationId} was not found.`);
+    }
+    const timestamp = nowIso();
+    const appliedTaskIds = recommendation.appliedTaskIds.includes(taskId) ? recommendation.appliedTaskIds : [
+        ...recommendation.appliedTaskIds,
+        taskId
+    ];
+    upsertRecommendationState(session, {
+        id: recommendation.id,
+        fingerprint: recommendation.fingerprint,
+        status: "active",
+        dismissedReason: null,
+        dismissedAt: null,
+        lastAppliedAt: timestamp,
+        appliedTaskIds,
+        updatedAt: timestamp
+    });
+    return findOperatorRecommendation(session, recommendationId) ?? recommendation;
+}
+export function buildRecommendationActionPlan(session, recommendationId, options = {}) {
+    const recommendation = findOperatorRecommendation(session, recommendationId);
+    if (!recommendation) {
+        throw new Error(`Recommendation ${recommendationId} was not found.`);
+    }
+    if (recommendation.kind === "ownership-config") {
+        throw new Error(`Recommendation ${recommendation.id} is advisory only. Run "${recommendation.commandHint}" and update the config manually.`);
+    }
+    if (recommendation.openFollowUpTaskIds.length > 0 && !options.force) {
+        throw new Error(`Recommendation ${recommendation.id} already has open follow-up task(s): ${recommendation.openFollowUpTaskIds.join(", ")}. Re-run with --force to enqueue another task.`);
+    }
+    const owner = recommendation.targetAgent === "operator" || recommendation.targetAgent === null ? "codex" : recommendation.targetAgent;
+    const prompt = recommendation.kind === "integration" ? [
+        "Coordinate and resolve overlapping agent work before landing.",
+        recommendation.detail,
+        recommendation.filePath ? `Primary hotspot: ${recommendation.filePath}` : null
+    ].filter(Boolean).join("\n") : [
+        "Pick up ownership-aware handoff work from Kavi.",
+        recommendation.detail,
+        recommendation.filePath ? `Focus path: ${recommendation.filePath}` : null
+    ].filter(Boolean).join("\n");
+    return {
+        recommendation,
+        owner,
+        prompt,
+        routeReason: `Queued from Kavi recommendation ${recommendation.id}.`,
+        routeStrategy: "manual",
+        routeConfidence: 1,
+        claimedPaths: recommendation.filePath ? [
+            recommendation.filePath
+        ] : [],
+        routeMetadata: {
+            recommendationId: recommendation.id,
+            recommendationKind: recommendation.kind
+        }
+    };
 }
 
 

package/dist/reports.js

@@ -0,0 +1,118 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ensureDir, fileExists, readJson, writeJson } from "./fs.js";
+function reportPath(paths, reportId) {
+    return path.join(paths.reportsDir, `${reportId}.json`);
+}
+function asStringArray(value) {
+    return Array.isArray(value) ? value.map((item)=>String(item)) : [];
+}
+function normalizeTaskResult(value) {
+    return {
+        taskId: String(value.taskId),
+        owner: value.owner === "codex" || value.owner === "claude" || value.owner === "router" ? value.owner : "router",
+        title: typeof value.title === "string" ? value.title : "",
+        summary: typeof value.summary === "string" ? value.summary : "",
+        claimedPaths: asStringArray(value.claimedPaths),
+        finishedAt: typeof value.finishedAt === "string" ? value.finishedAt : ""
+    };
+}
+function normalizeAgentChange(value) {
+    return {
+        agent: value.agent === "claude" ? "claude" : "codex",
+        paths: asStringArray(value.paths)
+    };
+}
+function normalizeSnapshotCommit(value) {
+    return {
+        agent: value.agent === "claude" ? "claude" : "codex",
+        commit: typeof value.commit === "string" ? value.commit : "",
+        createdCommit: value.createdCommit === true
+    };
+}
+function normalizeLandReport(report) {
+    return {
+        id: String(report.id),
+        sessionId: String(report.sessionId),
+        goal: typeof report.goal === "string" ? report.goal : null,
+        createdAt: typeof report.createdAt === "string" ? report.createdAt : "",
+        targetBranch: typeof report.targetBranch === "string" ? report.targetBranch : "",
+        integrationBranch: typeof report.integrationBranch === "string" ? report.integrationBranch : "",
+        integrationPath: typeof report.integrationPath === "string" ? report.integrationPath : "",
+        validationCommand: typeof report.validationCommand === "string" ? report.validationCommand : "",
+        validationStatus: report.validationStatus === "ran" || report.validationStatus === "skipped" || report.validationStatus === "not_configured" ? report.validationStatus : "not_configured",
+        validationDetail: typeof report.validationDetail === "string" ? report.validationDetail : "",
+        changedByAgent: Array.isArray(report.changedByAgent) ? report.changedByAgent.map((item)=>normalizeAgentChange(item)) : [],
+        completedTasks: Array.isArray(report.completedTasks) ? report.completedTasks.map((item)=>normalizeTaskResult(item)) : [],
+        snapshotCommits: Array.isArray(report.snapshotCommits) ? report.snapshotCommits.map((item)=>normalizeSnapshotCommit(item)) : [],
+        commandsRun: asStringArray(report.commandsRun),
+        reviewThreadsLanded: typeof report.reviewThreadsLanded === "number" ? report.reviewThreadsLanded : 0,
+        openReviewThreadsRemaining: typeof report.openReviewThreadsRemaining === "number" ? report.openReviewThreadsRemaining : 0,
+        summary: asStringArray(report.summary)
+    };
+}
+export function buildLandReport(params) {
+    const changedSummary = params.changedByAgent.map((changeSet)=>`${changeSet.agent}: ${changeSet.paths.length} path(s)`).join(" | ");
+    const validation = params.validationCommand.trim() ? params.validationStatus === "ran" ? `Validation ran with "${params.validationCommand.trim()}".` : params.validationStatus === "skipped" ? params.validationDetail : "No validation command was configured." : "No validation command was configured.";
+    return {
+        id: params.id,
+        sessionId: params.sessionId,
+        goal: params.goal,
+        createdAt: params.createdAt,
+        targetBranch: params.targetBranch,
+        integrationBranch: params.integrationBranch,
+        integrationPath: params.integrationPath,
+        validationCommand: params.validationCommand,
+        validationStatus: params.validationStatus,
+        validationDetail: params.validationDetail,
+        changedByAgent: params.changedByAgent.map((item)=>normalizeAgentChange(item)),
+        completedTasks: params.completedTasks.map((item)=>normalizeTaskResult(item)),
+        snapshotCommits: params.snapshotCommits.map((item)=>normalizeSnapshotCommit(item)),
+        commandsRun: [
+            ...params.commandsRun
+        ],
+        reviewThreadsLanded: params.reviewThreadsLanded,
+        openReviewThreadsRemaining: params.openReviewThreadsRemaining,
+        summary: [
+            `Merged managed work into ${params.targetBranch}.`,
+            changedSummary || "No worktree changes were recorded before landing.",
+            validation,
+            params.reviewThreadsLanded > 0 ? `${params.reviewThreadsLanded} review thread(s) were marked as landed.` : "No review threads were marked as landed."
+        ]
+    };
+}
+export async function saveLandReport(paths, report) {
+    await ensureDir(paths.reportsDir);
+    await writeJson(reportPath(paths, report.id), report);
+}
+export async function loadLandReport(paths, reportId) {
+    const filePath = reportPath(paths, reportId);
+    if (!await fileExists(filePath)) {
+        return null;
+    }
+    return normalizeLandReport(await readJson(filePath));
+}
+export async function listLandReports(paths) {
+    if (!await fileExists(paths.reportsDir)) {
+        return [];
+    }
+    const entries = await fs.readdir(paths.reportsDir, {
+        withFileTypes: true
+    });
+    const reports = [];
+    for (const entry of entries){
+        if (!entry.isFile() || !entry.name.endsWith(".json")) {
+            continue;
+        }
+        const report = await readJson(path.join(paths.reportsDir, entry.name));
+        reports.push(normalizeLandReport(report));
+    }
+    return reports.sort((left, right)=>right.createdAt.localeCompare(left.createdAt));
+}
+export async function loadLatestLandReport(paths) {
+    const reports = await listLandReports(paths);
+    return reports[0] ?? null;
+}
+
+
+//# sourceURL=reports.ts

package/dist/rpc.js

@@ -99,7 +99,26 @@ export async function rpcEnqueueTask(paths, params) {
         routeMetadata: params.routeMetadata,
         claimedPaths: params.claimedPaths,
         routeStrategy: params.routeStrategy,
-        routeConfidence: params.routeConfidence
+        routeConfidence: params.routeConfidence,
+        ...params.recommendationId ? {
+            recommendationId: params.recommendationId
+        } : {},
+        ...params.recommendationKind ? {
+            recommendationKind: params.recommendationKind
+        } : {}
+    });
+}
+export async function rpcDismissRecommendation(paths, params) {
+    await sendRpcRequest(paths, "dismissRecommendation", {
+        recommendationId: params.recommendationId,
+        ...params.reason ? {
+            reason: params.reason
+        } : {}
+    });
+}
+export async function rpcRestoreRecommendation(paths, params) {
+    await sendRpcRequest(paths, "restoreRecommendation", {
+        recommendationId: params.recommendationId
     });
 }
 export async function rpcResolveApproval(paths, params) {

package/dist/session.js

@@ -36,6 +36,7 @@ export async function createSessionRecord(paths, config, runtime, sessionId, bas
         decisions: [],
         pathClaims: [],
         reviewNotes: [],
+        recommendationStates: [],
         agentStatus: {
             codex: initialAgentStatus("codex", "codex-app-server"),
             claude: initialAgentStatus("claude", "claude-print")
@@ -85,6 +86,16 @@ export async function loadSessionRecord(paths) {
             landedAt: typeof note.landedAt === "string" ? note.landedAt : null,
             followUpTaskIds: Array.isArray(note.followUpTaskIds) ? note.followUpTaskIds.map((item)=>String(item)) : []
         })) : [];
+    record.recommendationStates = Array.isArray(record.recommendationStates) ? record.recommendationStates.map((state)=>({
+            id: String(state.id),
+            fingerprint: typeof state.fingerprint === "string" ? state.fingerprint : "",
+            status: state.status === "dismissed" ? "dismissed" : "active",
+            dismissedReason: typeof state.dismissedReason === "string" ? state.dismissedReason : null,
+            dismissedAt: typeof state.dismissedAt === "string" ? state.dismissedAt : null,
+            lastAppliedAt: typeof state.lastAppliedAt === "string" ? state.lastAppliedAt : null,
+            appliedTaskIds: Array.isArray(state.appliedTaskIds) ? state.appliedTaskIds.map((item)=>String(item)) : [],
+            updatedAt: typeof state.updatedAt === "string" ? state.updatedAt : nowIso()
+        })) : [];
     return record;
 }
 export async function saveSessionRecord(paths, record) {