refactor: remove KVARK, enterprise packs and the compliance subsystem (P1.4, P1.6)

KVARK is the commercial enterprise product and is not part of the community
edition. The agent's KVARK tools were never wired into the server, so
removing them changes no runtime behaviour beyond the routes listed here.

- agent: delete kvark-tools; CombinedRetrieval and formatCombinedResult now
  merge workspace and personal memory only (no KVARK lane, no source
  conflict note); connector substrate is always 'waggle'
- agent: promote_skill stops at workspace scope; team and enterprise scopes
  answer "not available in this edition" instead of an upgrade prompt
- server: delete src/kvark and GET /api/marketplace/enterprise-packs
- marketplace: delete ENTERPRISE_PACKS
- compliance (EU AI Act dashboard, its templates and the KVARK template
  seeded on every boot): delete core/src/compliance, the /api/compliance/*
  routes, agent compliance-pdf and the Cockpit compliance panel. The
  ai_interactions table lives in the memory substrate and goes with P1.5.
This commit is contained in:
shumeiko.it
2026-10-20 00:27:02 +02:00
parent 10ad678547
commit b734c1d3d2
53 changed files with 56 additions and 6936 deletions

View File

@@ -1,27 +1,20 @@
/**
* Combined Retrieval — merges workspace memory, personal memory, and KVARK enterprise search.
* Combined Retrieval — merges workspace memory and personal memory.
*
* This is the core merge engine for Milestone B. It does NOT format output for
* the agent (that's search_memory's job in B2). It returns structured data with
* source attribution so the consumer can format however it needs.
* It does NOT format output for the agent (that's search_memory's job). It
* returns structured data with source attribution so the consumer can format
* however it needs.
*
* Design:
* - Pure data in, pure data out — no side effects, no framework deps
* - KVARK is only called when local results are insufficient
* - Every result carries explicit source attribution
* - KVARK failures degrade gracefully (local results preserved, error captured)
*/
import {
parseSearchResults,
type KvarkClientLike,
type KvarkStructuredResult,
} from './kvark-tools.js';
import { logTurnEvent } from './turn-context.js';
// ── Public types ──────────────────────────────────────────────────────────
export type ResultSource = 'workspace' | 'personal' | 'kvark';
export type ResultSource = 'workspace' | 'personal';
export interface CombinedResult {
content: string;
@@ -29,13 +22,9 @@ export interface CombinedResult {
attribution: string;
score: number;
metadata: {
// Memory-sourced
frameId?: number;
frameType?: string;
importance?: string;
// KVARK-sourced
documentId?: number;
documentType?: string | null;
};
}
@@ -43,14 +32,6 @@ export interface CombinedRetrievalResult {
query: string;
workspaceResults: CombinedResult[];
personalResults: CombinedResult[];
kvarkResults: CombinedResult[];
kvarkAvailable: boolean;
kvarkSkipped: boolean;
kvarkError?: string;
/** True when workspace memory and KVARK results may disagree on the same topic */
hasConflict: boolean;
/** Human-readable note explaining detected conflict (undefined when no conflict) */
conflictNote?: string;
}
export interface CombinedSearchOptions {
@@ -83,71 +64,6 @@ export interface MemorySearchResultLike {
export interface CombinedRetrievalDeps {
workspaceSearch: MemorySearchLike | null;
personalSearch: MemorySearchLike;
kvarkClient: KvarkClientLike | null;
}
// ── Constants ─────────────────────────────────────────────────────────────
/** Minimum local results with strong scores before we skip KVARK */
const LOCAL_COVERAGE_MIN_COUNT = 3;
/** Score threshold to consider a local result "strong" */
const LOCAL_COVERAGE_SCORE_THRESHOLD = 0.7;
/** Minimum score for a result to participate in conflict detection */
const CONFLICT_SCORE_THRESHOLD = 0.6;
// ── Conflict detection ───────────────────────────────────────────────────
/** Status/decision keywords grouped by polarity */
const POSITIVE_STATUS = ['approved', 'accepted', 'selected', 'chose', 'chosen', 'decided', 'confirmed', 'active', 'completed', 'launched', 'enabled'];
const NEGATIVE_STATUS = ['rejected', 'cancelled', 'canceled', 'postponed', 'deprecated', 'deferred', 'suspended', 'disabled', 'abandoned', 'declined', 'revoked'];
/**
* Detect potential conflict between workspace memory and KVARK results.
*
* Conservative heuristic — only flags when:
* 1. Both sources have relevant results (score ≥ threshold)
* 2. Top results contain contradictory status/decision language
*
* Returns null when no conflict detected, or a short explanatory note.
*/
export function detectConflict(
workspaceResults: CombinedResult[],
kvarkResults: CombinedResult[],
): string | null {
// Need strong results from both sources
const strongWs = workspaceResults.filter(r => r.score >= CONFLICT_SCORE_THRESHOLD);
const strongKvark = kvarkResults.filter(r => r.score >= CONFLICT_SCORE_THRESHOLD);
if (strongWs.length === 0 || strongKvark.length === 0) return null;
// Check top results (up to 3 from each) for status polarity conflict
const wsTexts = strongWs.slice(0, 3).map(r => r.content.toLowerCase());
const kvarkTexts = strongKvark.slice(0, 3).map(r => r.content.toLowerCase());
const wsPolarity = extractPolarity(wsTexts);
const kvarkPolarity = extractPolarity(kvarkTexts);
// Conflict: one source is positive, the other is negative
if (wsPolarity === 'positive' && kvarkPolarity === 'negative') {
return 'Workspace memory contains affirmative language (approved/selected/active) while enterprise documents contain contradictory language (rejected/cancelled/deprecated). These sources may be out of sync.';
}
if (wsPolarity === 'negative' && kvarkPolarity === 'positive') {
return 'Enterprise documents contain affirmative language while workspace memory contains contradictory language. The enterprise source may be more current.';
}
return null;
}
type Polarity = 'positive' | 'negative' | 'neutral';
function extractPolarity(texts: string[]): Polarity {
const combined = texts.join(' ');
const hasPositive = POSITIVE_STATUS.some(w => combined.includes(w));
const hasNegative = NEGATIVE_STATUS.some(w => combined.includes(w));
// Only assign polarity when one side dominates
if (hasPositive && !hasNegative) return 'positive';
if (hasNegative && !hasPositive) return 'negative';
return 'neutral';
}
// ── Helpers ───────────────────────────────────────────────────────────────
@@ -170,38 +86,6 @@ export function mapMemoryResult(
};
}
/** Map a KvarkStructuredResult into a CombinedResult */
export function mapKvarkResult(result: KvarkStructuredResult): CombinedResult {
return {
content: result.content,
source: 'kvark',
attribution: result.attribution,
score: result.score,
metadata: {
documentId: result.documentId,
documentType: result.documentType,
},
};
}
/** Check whether local results are strong enough to skip KVARK */
export function hasSufficientLocalCoverage(results: CombinedResult[]): boolean {
const strongResults = results.filter(r => r.score >= LOCAL_COVERAGE_SCORE_THRESHOLD);
return strongResults.length >= LOCAL_COVERAGE_MIN_COUNT;
}
/** Decide whether KVARK should be queried */
export function shouldQueryKvark(
kvarkClient: KvarkClientLike | null,
scope: 'all' | 'personal' | 'workspace',
localResults: CombinedResult[],
): boolean {
if (!kvarkClient) return false;
if (scope === 'personal' || scope === 'workspace') return false;
if (hasSufficientLocalCoverage(localResults)) return false;
return true;
}
// ── Main class ────────────────────────────────────────────────────────────
export class CombinedRetrieval {
@@ -215,61 +99,15 @@ export class CombinedRetrieval {
const { limit = 10, profile = 'balanced', scope = 'all', turnId } = opts;
logTurnEvent(turnId, { stage: 'retrieval.enter', queryChars: query.length, limit, profile, scope });
// 1. Search workspace memory
const workspaceResults = await this.searchWorkspace(query, limit, profile, scope);
// 2. Search personal memory
const personalResults = await this.searchPersonal(query, limit, profile, scope);
// 3. Decide whether to call KVARK
const localResults = [...workspaceResults, ...personalResults];
const kvarkAvailable = this.deps.kvarkClient !== null;
const callKvark = shouldQueryKvark(this.deps.kvarkClient, scope, localResults);
if (!callKvark) {
logTurnEvent(turnId, {
stage: 'retrieval.exit',
workspaceHits: workspaceResults.length,
personalHits: personalResults.length,
kvarkHits: 0,
kvarkSkipped: kvarkAvailable,
});
return {
query,
workspaceResults,
personalResults,
kvarkResults: [],
kvarkAvailable,
kvarkSkipped: kvarkAvailable, // skipped only if it was available but we chose not to call
hasConflict: false,
};
}
// 4. Call KVARK (with graceful degradation)
const { kvarkResults, kvarkError } = await this.searchKvark(query, limit);
// 5. Detect potential conflict between workspace memory and KVARK
const conflictNote = detectConflict(workspaceResults, kvarkResults);
logTurnEvent(turnId, {
stage: 'retrieval.exit',
workspaceHits: workspaceResults.length,
personalHits: personalResults.length,
kvarkHits: kvarkResults.length,
kvarkError: kvarkError ?? null,
hasConflict: conflictNote !== null,
});
return {
query,
workspaceResults,
personalResults,
kvarkResults,
kvarkAvailable: true,
kvarkSkipped: false,
kvarkError,
hasConflict: conflictNote !== null,
conflictNote: conflictNote ?? undefined,
};
return { query, workspaceResults, personalResults };
}
private async searchWorkspace(
@@ -290,17 +128,4 @@ export class CombinedRetrieval {
const results = await this.deps.personalSearch.search(query, { limit, profile });
return results.map(r => mapMemoryResult(r, 'personal'));
}
private async searchKvark(
query: string, limit: number,
): Promise<{ kvarkResults: CombinedResult[]; kvarkError?: string }> {
try {
const response = await this.deps.kvarkClient!.search(query, { limit });
const structured = parseSearchResults(response);
return { kvarkResults: structured.map(mapKvarkResult) };
} catch (err) {
const message = err instanceof Error ? err.message : 'Unknown KVARK error';
return { kvarkResults: [], kvarkError: message };
}
}
}

View File

@@ -1,343 +0,0 @@
/**
* Skills 2.0 gap H — boardroom-grade compliance report PDF.
*
* Consumes an AuditReport (from @waggle/core/compliance) and produces a
* multi-page PDF styled with Waggle's Hive DS tokens (honey #E5A000).
* The layout is designed for the KVARK sales pitch: readable at arm's
* length, executive summary on page 1, detail tables on subsequent
* pages, page numbers, metadata header.
*
* Sections:
* 1. Cover — org name, risk level, report period, generated-at
* 2. Executive Summary — compliance status + status badges
* 3. Article status grid (Art 12/14/19/26/50)
* 4. Model Inventory table
* 5. Human Oversight Log table
* 6. Harvest Provenance table
* 7. Closing: totals + signature line
*/
import * as fs from 'node:fs';
import * as path from 'node:path';
import type { AuditReport, ComplianceStatus, ArticleStatus, AIActRiskLevel } from '@waggle/core';
import type { TDocumentDefinitions, Content, TableCell } from 'pdfmake/interfaces.js';
// Minimal surface of the pdfmake static we use (createPdf().getBuffer()).
interface PdfPrinter {
getBuffer(cb: (buffer: Buffer) => void): void;
}
interface PdfMakeStatic {
createPdf(docDef: TDocumentDefinitions): PdfPrinter;
}
/**
* Optional template-sourced overrides (M-03). Applied over the workspace-derived
* values so a single workspace can render under multiple branded templates without
* mutating the underlying WorkspaceConfig. Logo is deferred to Bucket 2.
*/
export interface PdfTemplateOverrides {
orgName?: string | null;
footerText?: string | null;
riskClassification?: AIActRiskLevel | null;
}
/** Hive DS color palette — match design-system conventions */
const HIVE_HONEY = '#E5A000';
const HIVE_DARK = '#08090C';
const HIVE_ACCENT = '#A78BFA';
const STATUS_COLORS: Record<ComplianceStatus['overall'], string> = {
compliant: '#22A06B',
warning: '#E5A000',
'non-compliant': '#C4342F',
};
const ARTICLE_LABELS: Record<string, string> = {
art12Logging: 'Art. 12 — Logging',
art14Oversight: 'Art. 14 — Human Oversight',
art19Retention: 'Art. 19 — Data Retention',
art26Monitoring: 'Art. 26 — Risk Classification',
art50Transparency: 'Art. 50 — Transparency',
};
function statusBadge(status: ArticleStatus['status']): Content {
const color = status === 'compliant' ? STATUS_COLORS.compliant
: status === 'warning' ? STATUS_COLORS.warning
: STATUS_COLORS['non-compliant'];
const label = status === 'compliant' ? 'COMPLIANT'
: status === 'warning' ? 'WARNING'
: 'NON-COMPLIANT';
return { text: label, bold: true, color, fontSize: 9 };
}
function coverContent(report: AuditReport, overrides?: PdfTemplateOverrides): Content[] {
const wsName = (overrides?.orgName && overrides.orgName.trim()) || report.workspace?.name || 'Personal Mind';
const riskLevel = (overrides?.riskClassification ?? report.workspace?.riskLevel ?? 'minimal').toUpperCase();
return [
{ text: 'AI ACT COMPLIANCE AUDIT', style: 'titleKicker', margin: [0, 120, 0, 6] },
{ text: wsName, style: 'title', margin: [0, 0, 0, 12] },
{ canvas: [{ type: 'line', x1: 0, y1: 0, x2: 500, y2: 0, lineWidth: 1.5, lineColor: HIVE_HONEY }], margin: [0, 0, 0, 24] },
{
columns: [
[
{ text: 'Risk Level', style: 'metaLabel' },
{ text: riskLevel, style: 'metaValue', margin: [0, 2, 0, 12] },
{ text: 'Period', style: 'metaLabel' },
{ text: `${report.report.period.from.slice(0, 10)} → ${report.report.period.to.slice(0, 10)}`, style: 'metaValue', margin: [0, 2, 0, 12] },
],
[
{ text: 'Overall Status', style: 'metaLabel' },
{ text: report.complianceStatus.overall.toUpperCase(), style: 'metaValue', color: STATUS_COLORS[report.complianceStatus.overall], margin: [0, 2, 0, 12] },
{ text: 'Generated', style: 'metaLabel' },
{ text: report.report.generatedAt.slice(0, 19).replace('T', ' ') + ' UTC', style: 'metaValue', margin: [0, 2, 0, 12] },
],
],
},
{ text: '', pageBreak: 'after' },
];
}
function articleGrid(status: ComplianceStatus): Content {
const rows: TableCell[][] = [
[
{ text: 'Article', style: 'tableHead' },
{ text: 'Status', style: 'tableHead' },
{ text: 'Detail', style: 'tableHead' },
],
];
for (const [key, label] of Object.entries(ARTICLE_LABELS)) {
const article = (status as unknown as Record<string, ArticleStatus>)[key];
if (!article) continue;
rows.push([
{ text: label, bold: true, fontSize: 10 },
statusBadge(article.status),
{ text: article.detail, fontSize: 9 },
]);
}
return {
table: { headerRows: 1, widths: [150, 80, '*'], body: rows },
layout: { hLineColor: () => '#E5E5E5', vLineColor: () => '#E5E5E5' },
margin: [0, 0, 0, 20],
};
}
function modelInventoryTable(report: AuditReport): Content {
if (report.modelInventory.length === 0) {
return { text: 'No model calls recorded in this period.', italics: true, color: '#6B6B6B', margin: [0, 0, 0, 16] };
}
const rows: TableCell[][] = [[
{ text: 'Model', style: 'tableHead' },
{ text: 'Provider', style: 'tableHead' },
{ text: 'Calls', style: 'tableHead', alignment: 'right' },
{ text: 'Input tok', style: 'tableHead', alignment: 'right' },
{ text: 'Output tok', style: 'tableHead', alignment: 'right' },
{ text: 'Cost (USD)', style: 'tableHead', alignment: 'right' },
]];
let totalCalls = 0, totalIn = 0, totalOut = 0, totalCost = 0;
for (const m of report.modelInventory) {
totalCalls += m.calls;
totalIn += m.inputTokens;
totalOut += m.outputTokens;
totalCost += m.costUsd;
rows.push([
{ text: m.model, fontSize: 9 },
{ text: m.provider, fontSize: 9 },
{ text: m.calls.toLocaleString('en-US'), fontSize: 9, alignment: 'right' },
{ text: m.inputTokens.toLocaleString('en-US'), fontSize: 9, alignment: 'right' },
{ text: m.outputTokens.toLocaleString('en-US'), fontSize: 9, alignment: 'right' },
{ text: `$${m.costUsd.toFixed(4)}`, fontSize: 9, alignment: 'right' },
]);
}
rows.push([
{ text: 'TOTAL', bold: true, fontSize: 9, fillColor: '#FAFAFA' },
{ text: '', fillColor: '#FAFAFA' },
{ text: totalCalls.toLocaleString('en-US'), bold: true, fontSize: 9, alignment: 'right', fillColor: '#FAFAFA' },
{ text: totalIn.toLocaleString('en-US'), bold: true, fontSize: 9, alignment: 'right', fillColor: '#FAFAFA' },
{ text: totalOut.toLocaleString('en-US'), bold: true, fontSize: 9, alignment: 'right', fillColor: '#FAFAFA' },
{ text: `$${totalCost.toFixed(4)}`, bold: true, fontSize: 9, alignment: 'right', fillColor: '#FAFAFA' },
]);
return {
table: { headerRows: 1, widths: ['*', 70, 40, 60, 60, 60], body: rows },
layout: { hLineColor: () => '#E5E5E5', vLineColor: () => '#E5E5E5' },
margin: [0, 0, 0, 20],
};
}
function oversightLogTable(report: AuditReport): Content {
if (report.humanOversightLog.length === 0) {
return { text: 'No human oversight events in this period.', italics: true, color: '#6B6B6B', margin: [0, 0, 0, 16] };
}
// Cap at 50 most recent events to keep the PDF tight; detail goes in JSON report
const shown = report.humanOversightLog.slice(-50);
const rows: TableCell[][] = [[
{ text: 'Timestamp', style: 'tableHead' },
{ text: 'Action', style: 'tableHead' },
{ text: 'Tool', style: 'tableHead' },
{ text: 'Detail', style: 'tableHead' },
]];
for (const e of shown) {
rows.push([
{ text: e.timestamp.slice(0, 19).replace('T', ' '), fontSize: 8 },
{ text: e.action, fontSize: 8, bold: true },
{ text: e.tool, fontSize: 8 },
{ text: e.detail.slice(0, 80), fontSize: 8 },
]);
}
const contents: Content[] = [{
table: { headerRows: 1, widths: [95, 60, 80, '*'], body: rows },
layout: { hLineColor: () => '#E5E5E5', vLineColor: () => '#E5E5E5' },
margin: [0, 0, 0, 8],
}];
if (report.humanOversightLog.length > 50) {
contents.push({
text: `Showing last 50 of ${report.humanOversightLog.length} events. Full log in JSON report.`,
fontSize: 8, italics: true, color: '#6B6B6B', margin: [0, 0, 0, 16],
});
}
return contents;
}
function provenanceTable(report: AuditReport): Content {
if (report.harvestProvenance.length === 0) {
return { text: 'No harvest provenance data for this period.', italics: true, color: '#6B6B6B', margin: [0, 0, 0, 16] };
}
const rows: TableCell[][] = [[
{ text: 'Source', style: 'tableHead' },
{ text: 'Imported At', style: 'tableHead' },
{ text: 'Items', style: 'tableHead', alignment: 'right' },
{ text: 'Frames', style: 'tableHead', alignment: 'right' },
]];
for (const p of report.harvestProvenance) {
rows.push([
{ text: p.source, fontSize: 9 },
{ text: p.importedAt.slice(0, 19).replace('T', ' '), fontSize: 9 },
{ text: p.itemsImported.toLocaleString('en-US'), fontSize: 9, alignment: 'right' },
{ text: p.framesCreated.toLocaleString('en-US'), fontSize: 9, alignment: 'right' },
]);
}
return {
table: { headerRows: 1, widths: ['*', 120, 60, 60], body: rows },
layout: { hLineColor: () => '#E5E5E5', vLineColor: () => '#E5E5E5' },
margin: [0, 0, 0, 20],
};
}
/** Build the pdfmake document definition. Exported for unit-test introspection. */
export function buildComplianceDocDefinition(
report: AuditReport,
overrides?: PdfTemplateOverrides,
): TDocumentDefinitions {
const wsName = (overrides?.orgName && overrides.orgName.trim()) || report.workspace?.name || 'Personal';
const footerExtra = overrides?.footerText?.trim() || null;
const content: Content[] = [
...coverContent(report, overrides),
{ text: 'Compliance Status', style: 'h1', margin: [0, 0, 0, 6] },
{
text: report.complianceStatus.overall === 'compliant'
? 'All monitored articles pass. The deployment operates within the AI Act framework for the selected period.'
: report.complianceStatus.overall === 'warning'
? 'One or more articles report warnings. Review the detail column for remediation.'
: 'At least one article is non-compliant. Remediation is required before the next audit.',
fontSize: 10, italics: true, color: '#333333', margin: [0, 0, 0, 16],
},
articleGrid(report.complianceStatus),
{ text: 'Model Inventory', style: 'h1', margin: [0, 0, 0, 6] },
{ text: `Tracked LLM/embedding model calls across the selected period. Totals appear on the bottom row.`, fontSize: 10, color: '#333333', margin: [0, 0, 0, 10] },
modelInventoryTable(report),
{ text: 'Human Oversight Log', style: 'h1', margin: [0, 0, 0, 6] },
{ text: `Art. 14 record of human approve/deny/modify actions on agent-proposed tool calls. Total this period: ${report.humanOversightLog.length}.`, fontSize: 10, color: '#333333', margin: [0, 0, 0, 10] },
...([] as Content[]).concat(oversightLogTable(report) as Content[] | Content),
{ text: 'Harvest Provenance', style: 'h1', margin: [0, 0, 0, 6] },
{ text: 'Art. 10 data-quality record of conversation imports and their downstream frame counts.', fontSize: 10, color: '#333333', margin: [0, 0, 0, 10] },
provenanceTable(report),
{ text: 'Summary', style: 'h1', margin: [0, 12, 0, 6] },
{
ul: [
`Total interactions logged: ${report.interactionCount.toLocaleString('en-US')}`,
`Models in inventory: ${report.modelInventory.length}`,
`Oversight events: ${report.humanOversightLog.length}`,
`Harvest sources: ${report.harvestProvenance.length}`,
],
fontSize: 10, color: '#333333', margin: [0, 0, 0, 20],
},
{ canvas: [{ type: 'line', x1: 0, y1: 0, x2: 500, y2: 0, lineWidth: 0.5, lineColor: '#CCCCCC' }], margin: [0, 12, 0, 6] },
{
text: `Report v${report.report.version} — generated by ${report.report.generatedBy}.`,
fontSize: 8, color: '#95A5A6', alignment: 'center',
},
];
return {
info: {
title: `Waggle AI Act Compliance Audit — ${wsName}`,
author: 'Waggle OS',
creator: 'Waggle OS Compliance Module',
subject: `AI Act compliance audit for period ${report.report.period.from} → ${report.report.period.to}`,
},
pageSize: 'A4',
pageMargins: [50, 60, 50, 60],
header: (currentPage: number) => currentPage > 1 ? {
columns: [
{ text: 'Waggle — AI Act Compliance Audit', fontSize: 8, color: '#95A5A6', margin: [50, 20, 0, 0] },
{ text: wsName, alignment: 'right', fontSize: 8, color: '#95A5A6', margin: [0, 20, 50, 0] },
],
} : undefined,
footer: (currentPage: number, pageCount: number) => ({
columns: [
{
text: footerExtra
? `Generated ${report.report.generatedAt.slice(0, 10)} · ${footerExtra}`
: `Generated ${report.report.generatedAt.slice(0, 10)}`,
fontSize: 8, color: '#95A5A6', margin: [50, 0, 0, 0],
},
{ text: `${currentPage} / ${pageCount}`, alignment: 'right', fontSize: 8, color: '#95A5A6', margin: [0, 0, 50, 0] },
],
}),
content,
styles: {
titleKicker: { fontSize: 11, color: HIVE_HONEY, bold: true, characterSpacing: 2 },
title: { fontSize: 30, bold: true, color: HIVE_DARK },
metaLabel: { fontSize: 8, color: '#95A5A6', characterSpacing: 1 },
metaValue: { fontSize: 14, bold: true, color: HIVE_DARK },
h1: { fontSize: 16, bold: true, color: HIVE_HONEY },
tableHead: { fontSize: 9, bold: true, color: HIVE_DARK, fillColor: '#FAFAFA' },
},
defaultStyle: { fontSize: 10, lineHeight: 1.35, color: '#333333' },
};
}
/**
* Render an AuditReport to a PDF Buffer.
* Uses dynamic import so pdfmake is only loaded when PDF generation runs.
*/
export async function renderComplianceReportPdf(
report: AuditReport,
overrides?: PdfTemplateOverrides,
): Promise<Buffer> {
const docDef = buildComplianceDocDefinition(report, overrides);
const pdfMakeModule = await import('pdfmake/build/pdfmake.js');
const pdfMake = (pdfMakeModule.default ?? pdfMakeModule) as unknown as PdfMakeStatic;
const printer = pdfMake.createPdf(docDef);
return new Promise<Buffer>((resolve, reject) => {
printer.getBuffer((buffer: Buffer) => {
if (buffer) resolve(buffer);
else reject(new Error('PDF generation returned empty buffer'));
});
});
}
/** Convenience: write the PDF to disk. Returns the absolute path. */
export async function writeComplianceReportPdf(
report: AuditReport,
outputPath: string,
overrides?: PdfTemplateOverrides,
): Promise<string> {
const buffer = await renderComplianceReportPdf(report, overrides);
fs.mkdirSync(path.dirname(outputPath), { recursive: true });
fs.writeFileSync(outputPath, buffer);
return path.resolve(outputPath);
}

View File

@@ -49,7 +49,7 @@ export interface WaggleConnector {
*/
readonly harvestAction?: { action: string; params?: Record<string, unknown> };
/** Which substrate manages this connector */
readonly substrate: 'waggle' | 'kvark';
readonly substrate: 'waggle';
/** CDN URL for SVG logo */
readonly logoUrl?: string;
/** Connector category */
@@ -78,7 +78,7 @@ export abstract class BaseConnector implements WaggleConnector {
abstract readonly service: string;
abstract readonly authType: 'bearer' | 'oauth2' | 'api_key' | 'basic';
abstract readonly actions: ConnectorAction[];
abstract readonly substrate: 'waggle' | 'kvark';
abstract readonly substrate: 'waggle';
readonly logoUrl?: string;
readonly category?: 'productivity' | 'development' | 'crm' | 'data' | 'communication' | 'storage' | 'integration';
readonly setupGuide?: string;

View File

@@ -382,11 +382,6 @@ export { CommandRegistry, AGENT_LOOP_REROUTE_PREFIX, type CommandDefinition, typ
export { registerWorkflowCommands } from './commands/workflow-commands.js';
export { registerMarketplaceCommands } from './commands/marketplace-commands.js';
export { createCronTools, type TurnOrigin } from './cron-tools.js';
export {
createKvarkTools, parseSearchResults,
type KvarkClientLike, type KvarkToolsDeps, type KvarkSearchResponseLike,
type KvarkAskResponseLike, type KvarkStructuredResult, type KvarkFeedbackResponseLike, type KvarkActionResponseLike,
} from './kvark-tools.js';
export { PERSONAS, getPersona, listPersonas, composePersonaPrompt, setPersonaDataDir, type AgentPersona } from './personas.js';
export {
loadCustomPersonas, saveCustomPersona, deleteCustomPersona,
@@ -470,12 +465,6 @@ export {
type SkillForAudit, type AuditTask, type SkillAuditOptions, type SkillAuditHooks,
type SkillAuditOutcome, type SkillAuditReport, type RewriteValidation,
} from './skill-audit.js';
export {
buildComplianceDocDefinition,
renderComplianceReportPdf,
writeComplianceReportPdf,
type PdfTemplateOverrides,
} from './compliance-pdf.js';
export {
watchSkillDirectory,
type SkillWatcherOptions, type SkillWatcherHandle,

View File

@@ -1,311 +0,0 @@
/**
* KVARK Agent Tools — kvark_search + kvark_ask_document.
*
* These tools are the agent-facing interface to KVARK's retrieval pipeline.
* All KVARK calls go through KvarkClient (from @waggle/server/kvark).
* Tools are only registered when KVARK is configured (Business/Enterprise tiers).
* Solo/Team users never see these tools.
*
* Design rules:
* - Tools use KvarkClient only — no direct fetch
* - Output is formatted text for the agent, not raw DTOs
* - Attribution structure preserved for Milestone B combined retrieval
* - Graceful degradation on all error paths
*/
import type { ToolDefinition } from './tools.js';
// ── Types from KVARK client (imported by interface, not package dep) ─────
/** Minimal KvarkClient interface — matches KvarkClient from @waggle/server/kvark */
export interface KvarkClientLike {
search(query: string, opts?: { limit?: number; offset?: number }): Promise<KvarkSearchResponseLike>;
askDocument(documentId: string, question: string): Promise<KvarkAskResponseLike>;
feedback?(documentId: number, query: string, useful: boolean, reason?: string): Promise<KvarkFeedbackResponseLike>;
action?(actionType: string, target: { entityType: string; entityId: string }, payload: Record<string, unknown>, reason: string, approvalReference?: string, workspaceId?: string): Promise<KvarkActionResponseLike>;
}
export interface KvarkFeedbackResponseLike {
ok: boolean;
}
export interface KvarkActionResponseLike {
ok: boolean;
data: {
status: 'executed' | 'denied' | 'queued';
actionId?: string;
auditRef?: string;
result?: Record<string, unknown>;
} | null;
error: { code: string; message: string } | null;
}
export interface KvarkSearchResponseLike {
results: KvarkSearchResultLike[];
total: number;
query: string;
}
export interface KvarkSearchResultLike {
document_id: number;
title: string;
snippet: string;
score: number;
document_type: string | null;
}
export interface KvarkAskResponseLike {
answer: string;
sources: string[];
}
// ── Structured result for Milestone B consumption ────────────────────────
/** Structured KVARK search result — used by combined retrieval (Milestone B) */
export interface KvarkStructuredResult {
content: string;
documentId: number;
title: string;
score: number;
documentType: string | null;
/** Attribution label for agent responses, e.g. "[KVARK: pdf / Project Status]" */
attribution: string;
}
/** Parses KvarkClient search response into structured results */
export function parseSearchResults(response: KvarkSearchResponseLike): KvarkStructuredResult[] {
return response.results.map(r => ({
content: r.snippet,
documentId: r.document_id,
title: r.title,
score: r.score,
documentType: r.document_type,
attribution: formatKvarkAttribution(r),
}));
}
/** Format a KVARK result into an attribution label */
function formatKvarkAttribution(result: KvarkSearchResultLike): string {
const parts = ['KVARK'];
if (result.document_type) parts.push(result.document_type);
parts.push(result.title);
return `[${parts.join(': ')}]`;
// Future: add connector, page when KVARK exposes them
// e.g. [KVARK: SharePoint / Project Status.pdf p.3]
}
// ── Tool output formatting ───────────────────────────────────────────────
function formatSearchOutput(response: KvarkSearchResponseLike, query: string): string {
if (response.results.length === 0) {
return `KVARK Search: "${query}" — no results found.`;
}
const header = `KVARK Search: "${query}" (${response.results.length} of ${response.total} results)\n`;
const items = response.results.map((r, i) => {
const typeLabel = r.document_type ? `[${r.document_type}]` : '[document]';
const snippet = r.snippet.length > 200 ? r.snippet.slice(0, 197) + '...' : r.snippet;
return `${i + 1}. ${typeLabel} ${r.title} (score: ${r.score.toFixed(2)})\n "${snippet}"\n ID: ${r.document_id}`;
});
return header + items.join('\n\n');
}
function formatAskOutput(response: KvarkAskResponseLike, documentId: string): string {
const sources = response.sources.length > 0
? `\n\nSources: ${response.sources.join(', ')}`
: '';
return `KVARK Document Answer (doc #${documentId}):\n\n${response.answer}${sources}`;
}
// ── Tool factory ─────────────────────────────────────────────────────────
export interface KvarkToolsDeps {
client: KvarkClientLike;
}
export function createKvarkTools(deps: KvarkToolsDeps): ToolDefinition[] {
const { client } = deps;
return [
// ── kvark_search ─────────────────────────────────────────────
{
name: 'kvark_search',
description:
'Search enterprise knowledge base via KVARK. Returns documents from connected sources (SharePoint, Jira, Slack, etc.) with relevance scores and source attribution. Use when the user needs information from enterprise systems beyond workspace memory.',
parameters: {
type: 'object',
properties: {
query: { type: 'string', description: 'Search query' },
limit: { type: 'number', description: 'Max results to return (default 10)' },
},
required: ['query'],
},
execute: async (args) => {
const query = args.query as string;
const limit = (args.limit as number) ?? 10;
try {
const response = await client.search(query, { limit });
return formatSearchOutput(response, query);
} catch (err) {
return handleKvarkError(err, 'search');
}
},
},
// ── kvark_feedback ─────────────────────────────────────────────
{
name: 'kvark_feedback',
description:
'Send feedback to KVARK about whether an enterprise search result was useful. Use this ONLY when a KVARK result materially influenced your answer — not for every search. Helps KVARK improve future retrieval quality.',
parameters: {
type: 'object',
properties: {
document_id: { type: 'number', description: 'Document ID from kvark_search or search_memory KVARK results' },
query: { type: 'string', description: 'The original search query that produced this result' },
useful: { type: 'boolean', description: 'Whether the result was useful for answering the user' },
reason: { type: 'string', description: 'Brief explanation of why the result was or was not useful (optional)' },
},
required: ['document_id', 'query', 'useful'],
},
execute: async (args) => {
const documentId = args.document_id as number;
const query = args.query as string;
const useful = args.useful as boolean;
const reason = args.reason as string | undefined;
if (!client.feedback) {
return 'Feedback not supported by this KVARK instance.';
}
try {
const response = await client.feedback(documentId, query, useful, reason);
return response.ok
? `Feedback recorded: ${useful ? 'useful' : 'not useful'} for document #${documentId}.`
: 'Feedback was sent but KVARK did not confirm storage.';
} catch (err) {
return handleKvarkError(err, 'feedback');
}
},
},
// ── kvark_action ──────────────────────────────────────────────
{
name: 'kvark_action',
description:
'Execute a governed enterprise action through KVARK (e.g., create a Jira ticket, post a Slack message, update a record). Requires user approval before execution. Use only when the user has explicitly asked for an action that touches enterprise systems.',
parameters: {
type: 'object',
properties: {
action_type: { type: 'string', description: 'Action identifier (e.g., "jira.create_comment", "slack.post_message", "sharepoint.update_file")' },
entity_type: { type: 'string', description: 'Target entity type (e.g., "issue", "channel", "document")' },
entity_id: { type: 'string', description: 'Target entity ID (e.g., "PROJ-142", "#general", "doc_123")' },
payload: { type: 'object', description: 'Action-specific data (e.g., { "comment": "..." } for a comment action)' },
reason: { type: 'string', description: 'Why this action is being performed — shown in governance audit trail' },
},
required: ['action_type', 'entity_type', 'entity_id', 'payload', 'reason'],
},
execute: async (args) => {
const actionType = args.action_type as string;
const entityType = args.entity_type as string;
const entityId = args.entity_id as string;
const payload = (args.payload as Record<string, unknown>) ?? {};
const reason = args.reason as string;
if (!client.action) {
return 'Governed actions are not supported by this KVARK instance.';
}
try {
const response = await client.action(
actionType,
{ entityType, entityId },
payload,
reason,
);
if (!response.ok) {
const errMsg = response.error?.message ?? 'Action was denied by KVARK governance policy.';
return `Action denied: ${errMsg}`;
}
const data = response.data!;
const parts = [`Action executed: ${actionType} on ${entityType}/${entityId}`];
if (data.actionId) parts.push(`Action ID: ${data.actionId}`);
if (data.auditRef) parts.push(`Audit reference: ${data.auditRef}`);
if (data.status === 'queued') parts.push('Status: queued for execution');
return parts.join('\n');
} catch (err) {
return handleKvarkError(err, 'action');
}
},
},
// ── kvark_ask_document ───────────────────────────────────────
{
name: 'kvark_ask_document',
description:
'Ask a focused question about a specific enterprise document. Returns an answer with source references. Use after kvark_search identifies a relevant document.',
parameters: {
type: 'object',
properties: {
document_id: { type: 'string', description: 'Document ID from kvark_search results' },
question: { type: 'string', description: 'Question about the document' },
},
required: ['document_id', 'question'],
},
execute: async (args) => {
const documentId = args.document_id as string;
const question = args.question as string;
try {
const response = await client.askDocument(documentId, question);
return formatAskOutput(response, documentId);
} catch (err) {
return handleKvarkError(err, 'ask');
}
},
},
];
}
// ── Error handling ───────────────────────────────────────────────────────
function handleKvarkError(err: unknown, operation: 'search' | 'ask' | 'feedback' | 'action'): string {
if (!(err instanceof Error)) {
return 'KVARK encountered an unexpected error. Try again or use workspace memory.';
}
switch (err.name) {
case 'KvarkUnavailableError':
return 'KVARK is not reachable. Using workspace memory only. Configure KVARK connection in Settings.';
case 'KvarkAuthError':
return 'KVARK authentication failed. Check KVARK credentials in Settings.';
case 'KvarkNotImplementedError':
if (operation === 'ask') {
return 'Document Q&A is not yet available on this KVARK instance. Use kvark_search to find relevant documents instead.';
}
if (operation === 'feedback') {
return 'Feedback is not yet available on this KVARK instance. This is non-blocking — continue normally.';
}
if (operation === 'action') {
return 'Governed actions are not yet available on this KVARK instance. The action was not executed.';
}
return 'This KVARK feature is not yet available.';
case 'KvarkNotFoundError':
if (operation === 'ask') {
return 'Document not found. The document may have been removed or the ID may be incorrect.';
}
return 'The requested resource was not found in KVARK.';
case 'KvarkServerError':
return `KVARK server error: ${err.message}. Try again in a moment.`;
default:
return `KVARK error: ${err.message}`;
}
}

View File

@@ -42,24 +42,6 @@ export function formatCombinedResult(result: CombinedRetrievalResult, hasWorkspa
}
}
// KVARK results
if (result.kvarkResults.length > 0) {
const header = '## Enterprise Knowledge (KVARK)';
// KVARK results: score only, no frame_type/importance
const entries = result.kvarkResults.map(r => formatResultEntry(r, false)).join('\n');
sections.push(`${header}\n${entries}`);
}
// Source conflict notice
if (result.hasConflict && result.conflictNote) {
sections.push(`## Source Conflict\n${result.conflictNote}\nReview both sources carefully and note which is more recent or authoritative.`);
}
// KVARK error notice
if (result.kvarkError && result.kvarkAvailable) {
sections.push(`> Enterprise search encountered an error: ${result.kvarkError}\n> Results shown are from local memory only.`);
}
if (sections.length === 0) {
return 'No relevant memories found.';
}

View File

@@ -57,13 +57,10 @@ export interface SkillToolsDeps {
/**
* Skills 2.0 gap E: promotion infrastructure. Each callback is optional.
* - getWorkspaceId / getTeamId resolve scope dirs dynamically at tool-call time.
* - hasTeamSkillLibrary / isEnterprise gate tier-restricted scopes.
* - improvementSignals records skill_promotion signals on successful moves.
*/
getWorkspaceId?: () => string | null;
getTeamId?: () => string | null;
hasTeamSkillLibrary?: () => boolean;
isEnterprise?: () => boolean;
improvementSignals?: ImprovementSignalStore;
/**
* Skills 2.0 gap A: session-message accessor for auto-extracting skills
@@ -668,14 +665,13 @@ Only use this after acquire_capability has identified a specific installable can
},
// Skills 2.0 gap E: promote_skill — move a skill up one scope rung.
// personal → workspace → team → enterprise. Enforces one-step-at-a-time,
// tier gates, and records a skill_promotion improvement signal on success.
// personal → workspace. Enforces one-step-at-a-time and records a
// skill_promotion improvement signal on success.
{
name: 'promote_skill',
description:
'Promote an installed skill one scope up (personal → workspace → team → enterprise). '
+ 'Team scope requires the teamSkillLibrary capability (TEAMS or ENTERPRISE tier). '
+ 'Enterprise scope requires ENTERPRISE tier. '
'Promote an installed skill one scope up (personal → workspace). '
+ 'Team and enterprise scopes are not available in this edition. '
+ 'The file is moved to the appropriate directory, frontmatter is rewritten '
+ '(scope + promoted_from history), and a skill_promotion signal is recorded.',
parameters: {
@@ -746,20 +742,13 @@ Only use this after acquire_capability has identified a specific installable can
);
}
// 4. Tier + context gating
// 4. Context gating. Team and enterprise skill libraries belong to
// team mode, which this edition does not ship.
if (target === 'workspace' && !workspaceId) {
return `Cannot promote to workspace scope: no active workspace. Switch to a workspace first.`;
}
if (target === 'team') {
if (!deps.hasTeamSkillLibrary?.()) {
return `Cannot promote to team scope: your plan does not include the team skill library. Upgrade to TEAMS or ENTERPRISE.`;
}
if (!teamId) {
return `Cannot promote to team scope: this workspace is not linked to a team.`;
}
}
if (target === 'enterprise' && !deps.isEnterprise?.()) {
return `Cannot promote to enterprise scope: requires ENTERPRISE tier. Contact sales for KVARK.`;
if (target === 'team' || target === 'enterprise') {
return `Cannot promote to ${target} scope: team and enterprise skill libraries are not available in this edition.`;
}
// 5. Resolve destination dir + path
@@ -818,8 +807,7 @@ Only use this after acquire_capability has identified a specific installable can
+ `- Promotion history: ${updatedFrontmatter.promoted_from!.join(' → ')} → ${target}\n`
+ `- Signal recorded: skill_promotion\n\n`
+ `The skill is available immediately at the new scope. Agents in other `
+ `workspaces${target === 'team' ? ' on this team' : target === 'enterprise' ? ' across the enterprise' : ''} `
+ `will pick it up on their next skill reload.`
+ `sessions will pick it up on their next skill reload.`
);
},
},