kibi-opencode 0.8.0 → 0.10.0

package/dist/idle-brief-audit.d.ts

@@ -0,0 +1,36 @@
+export interface AuditCursor {
+    lastTimestamp: string;
+    lastOperation: string;
+    entryCount: number;
+    fileSize: number;
+}
+export interface AuditDelta {
+    hasChanges: boolean;
+    entries: AuditEntry[];
+    newCursor: AuditCursor;
+    contentHash: string;
+}
+export interface AuditEntry {
+    timestamp: string;
+    operation: string;
+    entityId: string;
+    payload?: AuditEntityPayload | AuditRelationshipPayload | null;
+}
+export interface AuditEntityPayload {
+    kind: "entity";
+    entityType: string;
+    changeKind?: "created" | "updated";
+    title?: string;
+    source?: string;
+    textRef?: string;
+    properties: Record<string, unknown>;
+}
+export interface AuditRelationshipPayload {
+    kind: "relationship";
+    relationshipType: string;
+    properties: Record<string, unknown>;
+}
+export declare function computeAuditDelta(workspaceRoot: string, branch: string, previousCursor: AuditCursor | null): AuditDelta;
+export declare function getLatestAuditCursor(workspaceRoot: string, branch: string): AuditCursor | null;
+export declare function getAuditTailCursor(workspaceRoot: string, branch: string): AuditCursor | null;
+export declare function guardBranchChanged(startBranch: string, currentBranch: string): boolean;

package/dist/idle-brief-audit.js

@@ -0,0 +1,186 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parsePrologValue, parsePropertyList, splitTopLevelGeneral, } from "kibi-cli/prolog/codec";
+import { resolveAuditLogPath } from "./idle-brief-paths.js";
+function asOptionalString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+// Parse a single changeset line from the audit log
+function parseChangesetLine(line) {
+    const trimmedLine = line.trim();
+    if (!trimmedLine.startsWith("changeset(") || !trimmedLine.endsWith(").")) {
+        return null;
+    }
+    const argsLiteral = trimmedLine.slice("changeset(".length, -2);
+    const parts = splitTopLevelGeneral(argsLiteral, ",").map((part) => part.trim());
+    if (parts.length < 4) {
+        return null;
+    }
+    const timestamp = parsePrologValue(parts[0] ?? "");
+    const operation = parsePrologValue(parts[1] ?? "");
+    const entityId = parsePrologValue(parts[2] ?? "");
+    if (typeof timestamp !== "string" ||
+        typeof operation !== "string" ||
+        typeof entityId !== "string") {
+        return null;
+    }
+    const rawPayload = parts.slice(3).join(",");
+    const payload = parsePayload(rawPayload.trim());
+    return {
+        timestamp,
+        operation,
+        entityId,
+        ...(payload === undefined ? {} : { payload }),
+    };
+}
+function parsePayload(rawPayload) {
+    if (rawPayload === "null")
+        return null;
+    const match = rawPayload.match(/^([A-Za-z0-9_]+)-(.+)$/s);
+    if (!match)
+        return null;
+    const [, payloadType = "unknown", rawProps = ""] = match;
+    const properties = parsePropertyList(rawProps);
+    if (payloadType === "rel") {
+        return {
+            kind: "relationship",
+            relationshipType: payloadType,
+            properties,
+        };
+    }
+    const title = asOptionalString(properties.title);
+    const source = asOptionalString(properties.source);
+    const textRef = asOptionalString(properties.text_ref);
+    const changeKindRaw = properties.change_kind;
+    const changeKind = changeKindRaw === "created" || changeKindRaw === "updated"
+        ? changeKindRaw
+        : undefined;
+    return {
+        kind: "entity",
+        entityType: payloadType,
+        ...(changeKind ? { changeKind } : {}),
+        ...(title ? { title } : {}),
+        ...(source ? { source } : {}),
+        ...(textRef ? { textRef } : {}),
+        properties,
+    };
+}
+// implements REQ-opencode-kibi-briefing-v4
+// Read audit log and compute delta since last cursor
+export function computeAuditDelta(workspaceRoot, branch, previousCursor) {
+    const auditPath = resolveAuditLogPath(workspaceRoot, branch);
+    if (!fs.existsSync(auditPath)) {
+        return {
+            hasChanges: false,
+            entries: [],
+            newCursor: previousCursor ?? {
+                lastTimestamp: "",
+                lastOperation: "",
+                entryCount: 0,
+                fileSize: 0,
+            },
+            contentHash: "",
+        };
+    }
+    const content = fs.readFileSync(auditPath, "utf-8");
+    const lines = content
+        .split("\n")
+        .filter((l) => l.trim().includes("changeset("));
+    const fileSize = Buffer.byteLength(content, "utf-8");
+    // If no previous cursor or file hasn't grown, check if content changed
+    if (previousCursor &&
+        fileSize === previousCursor.fileSize &&
+        lines.length === previousCursor.entryCount) {
+        return {
+            hasChanges: false,
+            entries: [],
+            newCursor: previousCursor,
+            contentHash: computeSimpleHash(lines),
+        };
+    }
+    // Parse all entries
+    const entries = lines
+        .map(parseChangesetLine)
+        .filter((e) => e !== null)
+        .filter((e) => ["upsert", "upsert_rel", "delete"].includes(e.operation));
+    // If we have a previous cursor, filter to only new entries
+    let newEntries = entries;
+    if (previousCursor?.lastTimestamp) {
+        const lastIdx = entries.findIndex((e) => e.timestamp === previousCursor.lastTimestamp &&
+            e.operation === previousCursor.lastOperation);
+        if (lastIdx >= 0) {
+            newEntries = entries.slice(lastIdx + 1);
+        }
+    }
+    const lastEntry = entries[entries.length - 1];
+    const newCursor = {
+        lastTimestamp: lastEntry?.timestamp ?? "",
+        lastOperation: lastEntry?.operation ?? "",
+        entryCount: lines.length,
+        fileSize,
+    };
+    return {
+        hasChanges: newEntries.length > 0,
+        entries: newEntries,
+        newCursor,
+        contentHash: computeSimpleHash(lines),
+    };
+}
+function computeSimpleHash(lines) {
+    return crypto
+        .createHash("sha256")
+        .update(lines.join("\n"))
+        .digest("hex")
+        .slice(0, 16);
+}
+// implements REQ-opencode-kibi-briefing-v4
+// Extract the latest audit cursor from the most recent brief for this branch
+export function getLatestAuditCursor(workspaceRoot, branch) {
+    // Read .kb/briefs/ directory and find the latest brief for this branch
+    const briefsDir = path.join(workspaceRoot, ".kb", "briefs");
+    if (!fs.existsSync(briefsDir))
+        return null;
+    const files = fs
+        .readdirSync(briefsDir)
+        .filter((f) => f.endsWith("_brief.json") && !f.endsWith(".tmp"))
+        .map((f) => {
+        const fullPath = path.join(briefsDir, f);
+        const [rawTimestamp = "0"] = f.split("_");
+        const timestamp = Number.parseInt(rawTimestamp, 10);
+        return {
+            path: fullPath,
+            timestamp: Number.isNaN(timestamp) ? 0 : timestamp,
+        };
+    })
+        .sort((a, b) => b.timestamp - a.timestamp);
+    for (const file of files) {
+        try {
+            const brief = JSON.parse(fs.readFileSync(file.path, "utf-8"));
+            if (brief.branch === branch && brief.auditCursor) {
+                return brief.auditCursor;
+            }
+        }
+        catch {
+            // skip invalid JSON
+        }
+    }
+    return null;
+}
+export function getAuditTailCursor(
+// implements REQ-opencode-kibi-briefing-v6
+workspaceRoot, branch) {
+    const auditPath = resolveAuditLogPath(workspaceRoot, branch);
+    if (!fs.existsSync(auditPath)) {
+        return null;
+    }
+    const delta = computeAuditDelta(workspaceRoot, branch, null);
+    return delta.newCursor.entryCount > 0 || delta.newCursor.fileSize > 0
+        ? delta.newCursor
+        : null;
+}
+// implements REQ-opencode-kibi-briefing-v4
+// Guard: abort if branch changed since idle-start
+export function guardBranchChanged(startBranch, currentBranch) {
+    return startBranch !== currentBranch;
+}

package/dist/idle-brief-paths.d.ts

@@ -0,0 +1,6 @@
+export declare function resolveBriefsDir(workspaceRoot: string): string;
+export declare function resolveAuditLogPath(workspaceRoot: string, branch: string): string;
+export declare function resolveBriefFilePath(workspaceRoot: string, timestamp: number): string;
+export declare function resolveTempBriefPath(workspaceRoot: string, timestamp: number): string;
+export declare function atomicWriteBrief(workspaceRoot: string, timestamp: number, content: string): void;
+export declare function pruneOldBriefs(workspaceRoot: string, branch: string): void;

package/dist/idle-brief-paths.js

@@ -0,0 +1,120 @@
+import * as path from "node:path";
+import * as fs from "node:fs";
+import { loadBriefConfig } from "kibi-cli/brief-config";
+const TUI_SEEN_FILE = ".tui-seen.json";
+export function resolveBriefsDir(workspaceRoot) {
+    return path.join(workspaceRoot, ".kb", "briefs");
+}
+export function resolveAuditLogPath(workspaceRoot, branch) {
+    return path.join(workspaceRoot, ".kb", "branches", branch, "audit.log");
+}
+export function resolveBriefFilePath(workspaceRoot, timestamp) {
+    return path.join(resolveBriefsDir(workspaceRoot), `${timestamp}_brief.json`);
+}
+export function resolveTempBriefPath(workspaceRoot, timestamp) {
+    return path.join(resolveBriefsDir(workspaceRoot), `${timestamp}_brief.json.tmp`);
+}
+export function atomicWriteBrief(workspaceRoot, timestamp, content) {
+    const briefsDir = resolveBriefsDir(workspaceRoot);
+    if (!fs.existsSync(briefsDir)) {
+        fs.mkdirSync(briefsDir, { recursive: true });
+    }
+    const tempPath = resolveTempBriefPath(workspaceRoot, timestamp);
+    const finalPath = resolveBriefFilePath(workspaceRoot, timestamp);
+    fs.writeFileSync(tempPath, content, "utf-8");
+    fs.renameSync(tempPath, finalPath);
+}
+function extractTimestamp(fileName) {
+    const match = /^(\d+)_brief\.json$/.exec(fileName);
+    if (!match)
+        return null;
+    const n = Number(match[1]);
+    return Number.isFinite(n) ? n : null;
+}
+export function pruneOldBriefs(workspaceRoot, branch) {
+    const briefsDir = resolveBriefsDir(workspaceRoot);
+    if (!fs.existsSync(briefsDir))
+        return;
+    const shared = loadBriefConfig(workspaceRoot);
+    const maxPerBranch = Math.max(1, Number(shared.retention?.maxPerBranch ?? 200));
+    const maxAgeDays = Math.max(1, Number(shared.retention?.maxAgeDays ?? 14));
+    const keepUnread = shared.retention?.keepUnread ?? true;
+    const maxAgeMs = maxAgeDays * 24 * 60 * 60 * 1000;
+    const now = Date.now();
+    const branchFiles = [];
+    for (const file of fs.readdirSync(briefsDir)) {
+        if (!file.endsWith("_brief.json") || file.endsWith(".tmp"))
+            continue;
+        const ts = extractTimestamp(file);
+        if (ts === null)
+            continue;
+        const fullPath = path.join(briefsDir, file);
+        let parsed = {};
+        try {
+            parsed = JSON.parse(fs.readFileSync(fullPath, "utf-8"));
+        }
+        catch {
+            continue;
+        }
+        if (parsed.branch !== branch)
+            continue;
+        const nextItem = {
+            fullPath,
+            timestamp: ts,
+            unread: parsed.unread === true,
+        };
+        if (typeof parsed.contentHash === "string") {
+            nextItem.contentHash = parsed.contentHash;
+        }
+        branchFiles.push(nextItem);
+    }
+    branchFiles.sort((a, b) => b.timestamp - a.timestamp);
+    const keepSet = new Set();
+    for (const item of branchFiles.slice(0, maxPerBranch)) {
+        keepSet.add(item.fullPath);
+    }
+    if (keepUnread) {
+        for (const item of branchFiles) {
+            if (item.unread)
+                keepSet.add(item.fullPath);
+        }
+    }
+    for (const item of branchFiles) {
+        const olderThanThreshold = now - item.timestamp > maxAgeMs;
+        if (olderThanThreshold && !(keepUnread && item.unread)) {
+            keepSet.delete(item.fullPath);
+        }
+    }
+    for (const item of branchFiles) {
+        const shouldDelete = !keepSet.has(item.fullPath);
+        if (!shouldDelete)
+            continue;
+        try {
+            fs.unlinkSync(item.fullPath);
+        }
+        catch {
+            // best-effort cleanup
+        }
+    }
+    const remainingHashes = new Set(branchFiles
+        .filter((item) => keepSet.has(item.fullPath))
+        .map((item) => item.contentHash)
+        .filter((hash) => typeof hash === "string"));
+    const seenPath = path.join(briefsDir, TUI_SEEN_FILE);
+    try {
+        const parsed = JSON.parse(fs.readFileSync(seenPath, "utf-8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return;
+        const byBranch = parsed;
+        const existing = byBranch[branch];
+        if (!Array.isArray(existing))
+            return;
+        byBranch[branch] = existing.filter((entry) => typeof entry === "string" && remainingHashes.has(entry));
+        const tempPath = `${seenPath}.tmp`;
+        fs.writeFileSync(tempPath, JSON.stringify(byBranch, null, 2), "utf-8");
+        fs.renameSync(tempPath, seenPath);
+    }
+    catch {
+        // best-effort cleanup
+    }
+}

package/dist/idle-brief-reader.d.ts

@@ -0,0 +1,25 @@
+import { type IdleBriefEnvelope } from "./idle-brief-store.js";
+export declare function hasTuiSeenBrief(workspaceRoot: string, branch: string, contentHash: string): boolean;
+export declare function markBriefTuiSeen(workspaceRoot: string, branch: string, contentHash: string): void;
+/**
+ * Select the latest unread brief for the given branch.
+ *
+ * Scans `.kb/briefs/` for `{timestamp}_brief.json` files, ignoring `.tmp` files
+ * and invalid JSON. Filters by `branch`, supported schema version, and
+ * `unread === true`. Returns the brief with the highest filename timestamp,
+ * or null if no unread briefs exist.
+ */
+export declare function selectLatestUnreadBrief(workspaceRoot: string, branch: string): {
+    envelope: IdleBriefEnvelope;
+    filePath: string;
+} | null;
+/**
+ * Atomically mark a brief as read by setting `unread` to false.
+ *
+ * Uses the write-to-temp-then-rename pattern to ensure atomicity.
+ * Preserves ALL other envelope fields (contentHash, auditCursor, etc.).
+ *
+ * @param workspaceRoot - The root of the workspace
+ * @param briefPath - Absolute path to the brief file to mark as read
+ */
+export declare function markBriefRead(workspaceRoot: string, briefPath: string): void;

package/dist/idle-brief-reader.js

@@ -0,0 +1,142 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { resolveBriefsDir } from "./idle-brief-paths.js";
+import { isIdleBriefEnvelope, } from "./idle-brief-store.js";
+const BRIEF_FILENAME_RE = /^(\d+)_brief\.json$/;
+const TUI_SEEN_FILE = ".tui-seen.json";
+function resolveTuiSeenPath(workspaceRoot) {
+    return path.join(resolveBriefsDir(workspaceRoot), TUI_SEEN_FILE);
+}
+function readTuiSeenHashes(workspaceRoot, branch) {
+    const seenPath = resolveTuiSeenPath(workspaceRoot);
+    try {
+        const parsed = JSON.parse(fs.readFileSync(seenPath, "utf-8"));
+        if (!parsed || typeof parsed !== "object")
+            return new Set();
+        const byBranch = parsed;
+        const values = byBranch[branch];
+        if (!Array.isArray(values))
+            return new Set();
+        return new Set(values.filter((entry) => typeof entry === "string"));
+    }
+    catch {
+        return new Set();
+    }
+}
+export function hasTuiSeenBrief(workspaceRoot, branch, contentHash) {
+    return readTuiSeenHashes(workspaceRoot, branch).has(contentHash);
+}
+export function markBriefTuiSeen(workspaceRoot, branch, contentHash) {
+    const briefsDir = resolveBriefsDir(workspaceRoot);
+    fs.mkdirSync(briefsDir, { recursive: true });
+    const seenPath = resolveTuiSeenPath(workspaceRoot);
+    let parsed = {};
+    try {
+        const raw = JSON.parse(fs.readFileSync(seenPath, "utf-8"));
+        if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+            parsed = raw;
+        }
+    }
+    catch { }
+    const existing = Array.isArray(parsed[branch]) ? parsed[branch] : [];
+    const next = [contentHash, ...existing.filter((entry) => entry !== contentHash)].slice(0, 100);
+    parsed[branch] = next;
+    const tempPath = `${seenPath}.tmp`;
+    fs.writeFileSync(tempPath, JSON.stringify(parsed, null, 2), "utf-8");
+    fs.renameSync(tempPath, seenPath);
+}
+/**
+ * Extract the numeric timestamp prefix from a brief filename.
+ * Returns null if the filename does not match the expected pattern.
+ */
+function extractTimestamp(filename) {
+    const match = filename.match(BRIEF_FILENAME_RE);
+    if (!match)
+        return null;
+    return Number(match[1]);
+}
+/**
+ * Select the latest unread brief for the given branch.
+ *
+ * Scans `.kb/briefs/` for `{timestamp}_brief.json` files, ignoring `.tmp` files
+ * and invalid JSON. Filters by `branch`, supported schema version, and
+ * `unread === true`. Returns the brief with the highest filename timestamp,
+ * or null if no unread briefs exist.
+ */
+export function selectLatestUnreadBrief(
+// implements REQ-opencode-kibi-briefing-v4
+workspaceRoot, branch) {
+    const briefsDir = resolveBriefsDir(workspaceRoot);
+    if (!fs.existsSync(briefsDir)) {
+        return null;
+    }
+    const files = fs.readdirSync(briefsDir);
+    const candidates = [];
+    for (const file of files) {
+        // Ignore .tmp files
+        if (file.endsWith(".tmp"))
+            continue;
+        const timestamp = extractTimestamp(file);
+        if (timestamp === null)
+            continue;
+        const filePath = path.join(briefsDir, file);
+        let envelope;
+        try {
+            const raw = fs.readFileSync(filePath, "utf-8");
+            const parsed = JSON.parse(raw);
+            if (!isIdleBriefEnvelope(parsed)) {
+                continue;
+            }
+            envelope = parsed;
+        }
+        catch {
+            // Skip invalid JSON
+            continue;
+        }
+        // Filter by branch, schemaVersion, and unread status
+        if (envelope.branch === branch &&
+            (envelope.schemaVersion === "1.0" || envelope.schemaVersion === "2.0") &&
+            envelope.unread === true) {
+            candidates.push({ timestamp, envelope, filePath });
+        }
+    }
+    if (candidates.length === 0) {
+        return null;
+    }
+    // Sort by filename timestamp descending — latest first
+    candidates.sort((a, b) => b.timestamp - a.timestamp);
+    const latest = candidates[0];
+    if (!latest) {
+        return null;
+    }
+    return {
+        envelope: latest.envelope,
+        filePath: latest.filePath,
+    };
+}
+/**
+ * Atomically mark a brief as read by setting `unread` to false.
+ *
+ * Uses the write-to-temp-then-rename pattern to ensure atomicity.
+ * Preserves ALL other envelope fields (contentHash, auditCursor, etc.).
+ *
+ * @param workspaceRoot - The root of the workspace
+ * @param briefPath - Absolute path to the brief file to mark as read
+ */
+export function markBriefRead(
+// implements REQ-opencode-kibi-briefing-v4
+workspaceRoot, briefPath) {
+    const briefsDir = resolveBriefsDir(workspaceRoot);
+    const resolvedBriefPath = path.resolve(briefPath);
+    const resolvedBriefsDir = path.resolve(briefsDir);
+    // Security: ensure the brief path is within the expected briefs directory
+    if (!resolvedBriefPath.startsWith(resolvedBriefsDir + path.sep)) {
+        throw new Error(`Invalid brief path: ${briefPath} is not inside ${briefsDir}`);
+    }
+    const raw = fs.readFileSync(briefPath, "utf-8");
+    const brief = JSON.parse(raw);
+    brief.unread = false;
+    const tempPath = `${briefPath}.tmp`;
+    fs.writeFileSync(tempPath, JSON.stringify(brief, null, 2), "utf-8");
+    fs.renameSync(tempPath, briefPath);
+}

package/dist/idle-brief-runtime.d.ts

@@ -0,0 +1,48 @@
+import type { BriefingWorkspaceCtx } from "./briefing-runtime.js";
+import type { AuditDelta } from "./idle-brief-audit.js";
+import { type IdleBriefEnvelope } from "./idle-brief-store.js";
+export interface IdleBriefResult {
+    success: boolean;
+    briefPath: string | null;
+    envelope: IdleBriefEnvelope | null;
+}
+export interface CheckResult {
+    violations: Array<{
+        rule: string;
+        entityId: string;
+        description: string;
+        suggestion?: string;
+        source?: string;
+    }>;
+    count: number;
+    diagnostics: Array<{
+        category: string;
+        severity: string;
+        message: string;
+        file?: string;
+        suggestion?: string;
+    }>;
+}
+export interface IdleBriefStatement {
+    statement: string;
+    citationIds: string[];
+}
+export interface IdleBriefingResult {
+    briefingState: string;
+    tldr: string;
+    promptBlock: string;
+    citations: Array<{
+        id: string;
+        type?: string;
+        title?: string;
+        source?: string;
+        textRef?: string;
+    }>;
+    constraints?: IdleBriefStatement[];
+    regressionRisks?: IdleBriefStatement[];
+    missingEvidence?: IdleBriefStatement[];
+}
+export declare function generateIdleBrief(client: unknown, workspaceCtx: BriefingWorkspaceCtx, auditDelta: AuditDelta, sessionId: string, options?: {
+    sourceFiles?: string[];
+    changedEntityIds?: string[];
+}): Promise<IdleBriefResult>;