kibi-opencode 0.12.1 → 0.14.0

package/dist/graph-narrator.js

@@ -0,0 +1,408 @@
+// implements REQ-opencode-kibi-briefing-v6
+function asRecord(value) {
+    return typeof value === "object" && value !== null
+        ? value
+        : null;
+}
+function asString(value) {
+    return typeof value === "string" ? value : "";
+}
+function asStringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((entry) => typeof entry === "string")
+        : [];
+}
+function getSessionApi(client) {
+    const root = asRecord(client);
+    const session = asRecord(root?.session);
+    if (!session) {
+        return null;
+    }
+    const create = session.create;
+    const prompt = session.prompt;
+    if (typeof create !== "function" || typeof prompt !== "function") {
+        return null;
+    }
+    return {
+        create: create,
+        prompt: prompt,
+    };
+}
+function extractSessionId(response) {
+    const root = asRecord(response);
+    if (!root) {
+        return null;
+    }
+    const directId = asString(root.id).trim();
+    if (directId) {
+        return directId;
+    }
+    const data = asRecord(root.data);
+    return asString(data?.id).trim() || null;
+}
+function extractPromptResponseJson(response) {
+    const root = asRecord(response);
+    if (!root)
+        return null;
+    const data = asRecord(root.data);
+    const parts = Array.isArray(data?.parts)
+        ? data.parts
+        : Array.isArray(root.parts)
+            ? root.parts
+            : null;
+    if (!parts)
+        return null;
+    for (const part of parts) {
+        const record = asRecord(part);
+        if (record?.type !== "text") {
+            continue;
+        }
+        const text = asString(record.text);
+        if (!text) {
+            continue;
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+async function invokeTool(sessionApi, sessionID, tool, args) {
+    const response = await sessionApi.prompt({
+        sessionID,
+        parts: [{ type: "text", text: JSON.stringify({ tool, args }) }],
+        tools: { [tool]: true },
+        format: {
+            type: "json_schema",
+            schema: {
+                type: ["object", "array"],
+            },
+        },
+    });
+    return extractPromptResponseJson(response);
+}
+function inferTypeFromId(id) {
+    const prefix = id.split("-")[0]?.toLowerCase() ?? "entity";
+    switch (prefix) {
+        case "req":
+        case "scenario":
+        case "test":
+        case "adr":
+        case "flag":
+        case "event":
+        case "symbol":
+        case "fact":
+            return prefix;
+        case "scen":
+            return "scenario";
+        case "sym":
+            return "symbol";
+        default:
+            return prefix;
+    }
+}
+function humanizeType(type, count = 1) {
+    const singular = {
+        req: "requirement",
+        scenario: "scenario",
+        test: "test",
+        adr: "ADR",
+        flag: "flag",
+        event: "event",
+        symbol: "symbol",
+        fact: "fact",
+    }[type] ?? type;
+    if (count === 1) {
+        return singular;
+    }
+    if (singular === "ADR") {
+        return "ADRs";
+    }
+    return singular.endsWith("s") ? singular : `${singular}s`;
+}
+function humanizeDomain(domain) {
+    const normalized = domain.trim().toLowerCase();
+    switch (normalized) {
+        case "opencode":
+            return "OpenCode";
+        case "mcp":
+            return "MCP";
+        case "cli":
+            return "CLI";
+        case "vscode":
+            return "VSCode";
+        case "core":
+            return "Core";
+        case "requirements":
+            return "Requirements";
+        default:
+            return normalized ? normalized.charAt(0).toUpperCase() + normalized.slice(1) : "Changes";
+    }
+}
+function formatList(items) {
+    if (items.length === 0)
+        return "";
+    if (items.length === 1)
+        return items[0] ?? "";
+    if (items.length === 2)
+        return `${items[0]} and ${items[1]}`;
+    return `${items.slice(0, -1).join(", ")}, and ${items[items.length - 1]}`;
+}
+function normalizeEntity(record, idFallback) {
+    const properties = asRecord(record.properties) ?? {};
+    const id = asString(record.id || properties.id).trim() || idFallback;
+    const type = asString(record.type).trim() ||
+        asString(record.entityType).trim() ||
+        inferTypeFromId(id);
+    const title = asString(record.title).trim() ||
+        asString(properties.title).trim() ||
+        id;
+    const status = asString(record.status).trim() ||
+        asString(properties.status).trim() ||
+        asString(properties.change_kind).trim();
+    const source = asString(record.source).trim() ||
+        asString(properties.source).trim();
+    const tags = [
+        ...asStringArray(record.tags),
+        ...asStringArray(properties.tags),
+    ];
+    const factKind = asString(record.fact_kind).trim() ||
+        asString(properties.fact_kind).trim();
+    return {
+        id,
+        type,
+        title,
+        status,
+        source,
+        tags,
+        factKind,
+        removed: false,
+    };
+}
+function normalizeGraph(value) {
+    const root = asRecord(value);
+    if (!root) {
+        return null;
+    }
+    const edges = Array.isArray(root.edges)
+        ? root.edges
+            .map((edge) => {
+            const record = asRecord(edge);
+            if (!record)
+                return null;
+            const from = asString(record.from).trim();
+            const to = asString(record.to).trim();
+            const type = asString(record.type).trim();
+            return from && to && type ? { from, to, type } : null;
+        })
+            .filter((edge) => edge !== null)
+        : [];
+    return { edges };
+}
+function describeEntity(entity, id) {
+    if (!entity) {
+        return id;
+    }
+    return `${entity.title} (${entity.id})`;
+}
+function inferDomain(entity) {
+    const source = entity.source.replaceAll("\\", "/");
+    const packageMatch = source.match(/packages\/([^/]+)\//);
+    if (packageMatch?.[1]) {
+        return humanizeDomain(packageMatch[1]);
+    }
+    const tagDomain = entity.tags.find((tag) => ["cli", "mcp", "vscode", "opencode", "core"].includes(tag.toLowerCase()));
+    if (tagDomain) {
+        return humanizeDomain(tagDomain);
+    }
+    if (["req", "scenario", "test"].includes(entity.type)) {
+        return "Requirements";
+    }
+    return humanizeDomain(entity.type);
+}
+function classifyRelationship(relationship, entities) {
+    const fromEntity = entities.get(relationship.from);
+    const toEntity = entities.get(relationship.to);
+    const fromText = describeEntity(fromEntity, relationship.from);
+    const toText = describeEntity(toEntity, relationship.to);
+    switch (relationship.type) {
+        case "supersedes":
+            return `${toText} was superseded by ${fromText}`;
+        case "implements":
+            return `${fromText} now implements ${toText}`;
+        case "covered_by":
+            return `${fromText} gained test coverage via ${toText}`;
+        case "verified_by":
+            return `${fromText} is verified by ${toText}`;
+        case "specified_by":
+            return `${fromText} is specified by ${toText}`;
+        case "requires_property":
+            return `${fromText} constrains property ${toText}`;
+        case "constrains":
+            if (toEntity?.type === "fact" && toEntity.factKind === "subject") {
+                return `${fromText} is linked to fact ${toText}`;
+            }
+            return `${fromText} is linked to ${toText}`;
+        default:
+            return null;
+    }
+}
+function uniqueStrings(items) {
+    return [...new Set(items.filter(Boolean))];
+}
+function buildEntityChange(entity, relationships, graph) {
+    const label = describeEntity(entity, entity.id);
+    if (entity.removed) {
+        return `${label} was removed`;
+    }
+    if (entity.status === "superseded") {
+        return `${label} was marked superseded`;
+    }
+    const hasRelationshipChange = relationships.some((relationship) => relationship.from === entity.id || relationship.to === entity.id);
+    const hasGraphEdges = (graph?.edges.length ?? 0) > 0;
+    if (!hasRelationshipChange && !hasGraphEdges) {
+        return `${label} was created`;
+    }
+    return `${label} was updated`;
+}
+function summarizeTypes(entities) {
+    const counts = new Map();
+    for (const entity of entities) {
+        counts.set(entity.type, (counts.get(entity.type) ?? 0) + 1);
+    }
+    return formatList([...counts.entries()].map(([type, count]) => `${count} ${humanizeType(type, count)}`));
+}
+function summarizeTopChanges(domainChanges, relationshipChanges) {
+    const focus = relationshipChanges.length > 0 ? relationshipChanges : domainChanges;
+    const selected = focus.slice(0, 2);
+    return selected.length > 0 ? `Key changes: ${selected.join("; ")}.` : "";
+}
+function validationStatusText(checkResult) {
+    if (checkResult.count <= 0) {
+        return "All checks pass";
+    }
+    return `${checkResult.count} validation issue${checkResult.count === 1 ? "" : "s"}`;
+}
+async function loadEntity(sessionApi, sessionID, id) {
+    const response = await invokeTool(sessionApi, sessionID, "kb_query", { id, limit: 1 });
+    if (!Array.isArray(response)) {
+        throw new Error(`kb_query returned unsupported payload for ${id}`);
+    }
+    if (response.length === 0) {
+        return {
+            id,
+            type: inferTypeFromId(id),
+            title: id,
+            status: "removed",
+            source: "",
+            tags: [],
+            factKind: "",
+            removed: true,
+        };
+    }
+    const record = asRecord(response[0]);
+    if (!record) {
+        throw new Error(`kb_query returned invalid entity for ${id}`);
+    }
+    return normalizeEntity(record, id);
+}
+async function loadGraph(sessionApi, sessionID, id) {
+    const response = await invokeTool(sessionApi, sessionID, "kb_graph", {
+        seedIds: [id],
+        direction: "both",
+        depth: 2,
+        maxNodes: 100,
+        maxEdges: 200,
+    });
+    return normalizeGraph(response);
+}
+// implements REQ-opencode-kibi-briefing-v2
+export async function generateGraphNarrative(client, workspaceCtx, changedEntityIds, changedRelationships, checkResult) {
+    const uniqueIds = uniqueStrings(changedEntityIds);
+    if (uniqueIds.length === 0) {
+        return null;
+    }
+    const sessionApi = getSessionApi(client);
+    if (!sessionApi) {
+        return null;
+    }
+    let sessionID = null;
+    try {
+        const worker = await sessionApi.create({
+            directory: workspaceCtx.workspaceRoot,
+            title: `Kibi Graph Narrator (${workspaceCtx.branch})`,
+        });
+        sessionID = extractSessionId(worker);
+    }
+    catch {
+        return null;
+    }
+    if (!sessionID) {
+        return null;
+    }
+    const entities = new Map();
+    const graphs = new Map();
+    for (const id of uniqueIds) {
+        let entity;
+        try {
+            entity = await loadEntity(sessionApi, sessionID, id);
+        }
+        catch {
+            continue;
+        }
+        if (!entity) {
+            continue;
+        }
+        entities.set(id, entity);
+        if (entity.removed) {
+            graphs.set(id, null);
+            continue;
+        }
+        try {
+            graphs.set(id, await loadGraph(sessionApi, sessionID, id));
+        }
+        catch {
+            graphs.set(id, null);
+        }
+    }
+    const entityList = [...entities.values()];
+    if (entityList.length === 0) {
+        return null;
+    }
+    const relationshipChanges = uniqueStrings(changedRelationships
+        .map((relationship) => classifyRelationship(relationship, entities))
+        .filter((sentence) => !!sentence));
+    const domainMap = new Map();
+    for (const entity of entityList) {
+        const domain = inferDomain(entity);
+        const changes = domainMap.get(domain) ?? [];
+        changes.push(buildEntityChange(entity, changedRelationships, graphs.get(entity.id) ?? null));
+        domainMap.set(domain, changes);
+    }
+    const domains = [...domainMap.entries()]
+        .map(([name, changes]) => ({ name, changes: uniqueStrings(changes) }))
+        .sort((left, right) => left.name.localeCompare(right.name));
+    const domainNames = domains.map((domain) => domain.name);
+    const headline = `${summarizeTypes(entityList)} changed${domainNames.length > 1 ? ` across ${formatList(domainNames)} domains` : ""}.`;
+    const allDomainChanges = domains.flatMap((domain) => domain.changes);
+    const validationStatus = validationStatusText(checkResult);
+    const tldr = [
+        headline,
+        summarizeTopChanges(allDomainChanges, relationshipChanges),
+        validationStatus === "All checks pass"
+            ? "Validation remains clean."
+            : `${validationStatus}.`,
+    ]
+        .filter(Boolean)
+        .join(" ");
+    return {
+        headline,
+        tldr,
+        domains,
+        relationshipChanges,
+        validationStatus,
+    };
+}

package/dist/guidance-cache.d.ts

@@ -3,6 +3,8 @@ import type { RiskClass } from "./risk-classifier.js";
 /**
  * Cache key uniquely identifies a preflight context by combining
  * workspace root, branch, posture, risk class, and file bucket.
+ * Hard-enforcement callers may additionally pass scopeKey to prevent
+ * cross-session/worktree dirty-state cache hits. Advisory callers omit it.
  */
 export interface CacheKey {
     workspaceRoot: string;
@@ -10,6 +12,7 @@ export interface CacheKey {
     posture: RepoPosture;
     riskClass: RiskClass;
     fileBucket: string;
+    scopeKey?: string;
 }
 /**
  * Cache entry tracking when a preflight was last satisfied.

package/dist/guidance-cache.js

@@ -3,7 +3,7 @@
  * Serializes a CacheKey into a deterministic string for use as a Map key.
  */
 function serializeKey(key) {
-    return `${key.workspaceRoot}\0${key.branch}\0${key.posture}\0${key.riskClass}\0${key.fileBucket}`;
+    return `${key.workspaceRoot}\0${key.branch}\0${key.posture}\0${key.riskClass}\0${key.fileBucket}\0${key.scopeKey ?? ""}`;
 }
 /**
  * In-memory cache tracking satisfied preflight checks per unique context.

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

@@ -42,7 +42,14 @@ export interface IdleBriefingResult {
     regressionRisks?: IdleBriefStatement[];
     missingEvidence?: IdleBriefStatement[];
 }
+type IdleBriefRelationship = {
+    from: string;
+    to: string;
+    type: string;
+};
 export declare function generateIdleBrief(client: unknown, workspaceCtx: BriefingWorkspaceCtx, auditDelta: AuditDelta, sessionId: string, options?: {
     sourceFiles?: string[];
     changedEntityIds?: string[];
+    relationships?: IdleBriefRelationship[];
 }): Promise<IdleBriefResult>;
+export {};

package/dist/idle-brief-runtime.js

@@ -1,6 +1,7 @@
 // implements REQ-opencode-kibi-briefing-v4
 import { buildBriefingContext } from "./brief-intent.js";
 import { buildDeliveryReasons } from "./brief-delivery-reasons.js";
+import { generateGraphNarrative } from "./graph-narrator.js";
 import { atomicWriteBrief, pruneOldBriefs, resolveBriefFilePath, } from "./idle-brief-paths.js";
 import { computeContentHash, createBriefId, } from "./idle-brief-store.js";
 import { reconcileAuditEntries } from "./reconcile-engine.js";
@@ -318,7 +319,7 @@ function buildChangeNarrative(auditDelta) {
     }
     return lines;
 }
-function buildEnvelopeParts(briefId, type, sessionId, branch, createdAt, auditDelta, summary, counts, checkResult, briefingResult, deliveryReasons) {
+function buildEnvelopeParts(briefId, type, sessionId, branch, createdAt, auditDelta, summary, counts, checkResult, briefingResult, changeNarrative, deliveryReasons) {
     const reconciled = reconcileAuditEntries(auditDelta.entries);
     return {
         schemaVersion: "2.0",
@@ -350,7 +351,7 @@ function buildEnvelopeParts(briefId, type, sessionId, branch, createdAt, auditDe
             tldr: briefingResult.tldr || summary,
             promptBlock: briefingResult.promptBlock,
             citations: briefingResult.citations,
-            changeNarrative: buildChangeNarrative(auditDelta),
+            changeNarrative,
             ...(deliveryReasons ? { deliveryReasons } : {}),
             ...(briefingResult.constraints && briefingResult.constraints.length > 0
                 ? { constraints: briefingResult.constraints }
@@ -388,11 +389,15 @@ export async function generateIdleBrief(client, workspaceCtx, auditDelta, sessio
         : derivedSourceFiles.length > 0
             ? derivedSourceFiles
             : [auditDelta.entries[0]?.entityId ?? "unknown"];
+    const relationshipEntityIds = (options?.relationships ?? []).flatMap((relationship) => [relationship.from, relationship.to]);
+    const mergedChangedEntityIds = options?.changedEntityIds
+        ? [...new Set([...options.changedEntityIds, ...relationshipEntityIds])]
+        : relationshipEntityIds.length > 0
+            ? [...new Set(relationshipEntityIds)]
+            : undefined;
     const briefingContext = buildBriefingContext({
         sourceFiles,
-        ...(options?.changedEntityIds
-            ? { changedEntityIds: options.changedEntityIds }
-            : {}),
+        ...(mergedChangedEntityIds ? { changedEntityIds: mergedChangedEntityIds } : {}),
     });
     const { seedIds } = briefingContext;
     let checkResult;
@@ -431,6 +436,12 @@ export async function generateIdleBrief(client, workspaceCtx, auditDelta, sessio
     const isSuccess = violationsCount === 0;
     const type = isSuccess ? "success" : "warning";
     const summary = computeSummary(counts, violationsCount);
+    const changedEntityIdsForNarrative = mergedChangedEntityIds ?? [
+        ...reconciled.added.map((item) => item.id),
+        ...reconciled.modified.map((item) => item.id),
+        ...reconciled.removed.map((item) => item.id),
+    ];
+    const changedRelationships = options?.relationships ?? [];
     const deliveryReasons = buildDeliveryReasons({
         entitiesAdded: reconciled.added
             .filter((item) => item.id !== "workspace-sync")
@@ -444,6 +455,13 @@ export async function generateIdleBrief(client, workspaceCtx, auditDelta, sessio
         relationshipsChanged: counts.relationshipsChanged,
         validationCount: checkResult.count,
     });
+    const graphNarrative = await generateGraphNarrative(client, workspaceCtx, changedEntityIdsForNarrative, changedRelationships, checkResult);
+    const changeNarrative = graphNarrative?.relationshipChanges.length || graphNarrative?.domains.length
+        ? [
+            ...graphNarrative.relationshipChanges,
+            ...graphNarrative.domains.flatMap((domain) => domain.changes),
+        ]
+        : buildChangeNarrative(auditDelta);
     if (counts.entitiesAdded === 0 &&
         counts.entitiesModified === 0 &&
         counts.entitiesRemoved === 0 &&
@@ -455,7 +473,7 @@ export async function generateIdleBrief(client, workspaceCtx, auditDelta, sessio
     const briefId = createBriefId();
     const timestamp = Date.now();
     const createdAt = new Date().toISOString();
-    const envelopeWithoutHash = buildEnvelopeParts(briefId, type, sessionId, workspaceCtx.branch, createdAt, auditDelta, summary, counts, checkResult, briefingResult, deliveryReasons);
+    const envelopeWithoutHash = buildEnvelopeParts(briefId, type, sessionId, workspaceCtx.branch, createdAt, auditDelta, summary, counts, checkResult, briefingResult, changeNarrative, deliveryReasons);
     const contentHash = computeContentHash(envelopeWithoutHash);
     const envelope = {
         ...envelopeWithoutHash,

package/dist/kibi-checkpoint-runner.d.ts

@@ -0,0 +1,83 @@
+import { type KibiConfig } from "./config.js";
+import { type EnforcementLifecycleEvent, type PolicyLinkedEntityResult } from "./enforcement-policy.js";
+import type { E2eCoverageSignal } from "./e2e-coverage-signals.js";
+import type { PathKind } from "./path-kind.js";
+import { type CheckRunner, type SyncRunMetadata, type SyncRunner, type TimeoutHandle } from "./scheduler.js";
+import type { WorkContext } from "./work-context-resolver.js";
+export interface KibiCheckpointContext {
+    workContext: WorkContext;
+    config?: KibiConfig;
+    filePath?: string;
+    checkRules?: string[] | undefined;
+    maintenanceDegraded?: boolean;
+    hardGuidanceText?: string | null;
+    lifecycleEvents?: EnforcementLifecycleEvent[];
+    pathKinds?: PathKind[];
+    linkedEntityResults?: PolicyLinkedEntityResult[];
+    e2eSignals?: E2eCoverageSignal[];
+}
+export interface KibiCheckpointRunnerOptions {
+    config?: KibiConfig;
+    runSync?: SyncRunner;
+    runCheck?: CheckRunner;
+    onRunComplete?: (meta: SyncRunMetadata) => void;
+    timeoutMs?: number;
+    setTimeoutFn?: (fn: () => void, ms: number) => TimeoutHandle;
+    clearTimeoutFn?: (handle: TimeoutHandle) => void;
+}
+export interface KibiCheckpointMetadata {
+    fingerprint: string;
+    scopeKey: string;
+    worktree: string;
+    branch: string;
+    sessionId?: string;
+    agentIdentity: string;
+    guidanceRendered?: boolean;
+    guidanceText?: string;
+    sync?: SyncRunMetadata;
+    reason?: string;
+    timeoutMs?: number;
+    checkRules?: string[] | undefined;
+    restoreInstructions?: string;
+}
+export type KibiCheckpointRequestResult = {
+    kind: "requested";
+    metadata: KibiCheckpointMetadata;
+} | {
+    kind: "skip";
+    metadata: KibiCheckpointMetadata;
+} | {
+    kind: "hard_block";
+    metadata: KibiCheckpointMetadata;
+};
+export type KibiCheckpointRunResult = {
+    kind: "passed";
+    metadata: KibiCheckpointMetadata;
+} | {
+    kind: "hard_block";
+    metadata: KibiCheckpointMetadata;
+} | {
+    kind: "skip";
+    metadata: KibiCheckpointMetadata;
+};
+export declare class KibiCheckpointRunner {
+    private readonly config;
+    private readonly runSync;
+    private readonly runCheck;
+    private readonly onRunComplete;
+    private readonly timeoutMs;
+    private readonly setTimeoutFn;
+    private readonly clearTimeoutFn;
+    private readonly requested;
+    private readonly passed;
+    private readonly passedScopeKeysByFingerprint;
+    constructor(options?: KibiCheckpointRunnerOptions);
+    requestCheckpoint(context: KibiCheckpointContext, fingerprint: string): KibiCheckpointRequestResult;
+    isCheckpointPassed(fingerprint: string, context?: KibiCheckpointContext): boolean;
+    runCheckpoint(context: KibiCheckpointContext, fingerprint: string): Promise<KibiCheckpointRunResult>;
+    private baseMetadata;
+    private scopeKey;
+    private renderHardGuidance;
+    private withTimeout;
+    private recordPassed;
+}