@remnic/core 1.0.0

package/dist/transcript.d.ts

@@ -0,0 +1,171 @@
+import { PluginConfig, TranscriptEntry, Checkpoint } from './types.js';
+import { SessionIntegrityReport } from './session-integrity.js';
+
+/**
+ * Manages conversation transcript storage, checkpointing, and recall formatting.
+ *
+ * Transcripts are stored as JSONL files in a hierarchical structure:
+ *   transcripts/{channelType}/{channelId}.jsonl
+ *
+ * Channel types are extracted from sessionKey (discord, slack, cron, main, etc.)
+ * Checkpoints are used to preserve conversation context across compaction events.
+ */
+declare class TranscriptManager {
+    private transcriptsDir;
+    private checkpointPath;
+    private stateDir;
+    private toolUsageDir;
+    private config;
+    private sessionFootprintCache;
+    /** Default checkpoint TTL in hours */
+    private static readonly DEFAULT_CHECKPOINT_TTL_HOURS;
+    /** Approximate characters per token for rough estimation */
+    private static readonly CHARS_PER_TOKEN;
+    constructor(config: PluginConfig);
+    /**
+     * Parse a sessionKey to extract channel type and ID.
+     *
+     * SessionKey patterns:
+     *   - agent:<agent-id>:main → type="main", id="default"
+     *   - agent:<agent-id>:discord:channel:<channel-id> → type="discord", id="<channel-id>"
+     *   - agent:<agent-id>:cron:<job-id> → type="cron", id="<job-id>"
+     *   - agent:<agent-id>:slack:channel:<channel-id> → type="slack", id="<channel-id>"
+     *
+     * @returns Object with dir (channel type/channel id) and file (YYYY-MM-DD.jsonl)
+     */
+    getTranscriptPath(sessionKey: string): {
+        dir: string;
+        file: string;
+    };
+    /**
+     * Initialize the transcript manager by ensuring directories exist.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Best-effort list of sessionKeys that have transcript files on disk.
+     * This is used by cron-style tooling (hourly summaries, conversation indexing)
+     * to iterate across "active" sessions.
+     */
+    listSessionKeys(): Promise<string[]>;
+    getToolUsagePath(sessionKey: string): {
+        dir: string;
+        file: string;
+    };
+    appendToolUse(entry: {
+        timestamp: string;
+        sessionKey: string;
+        tool: string;
+    }): Promise<void>;
+    readToolUse(sessionKey: string, startTime: Date, endTime: Date): Promise<Array<{
+        timestamp: string;
+        sessionKey: string;
+        tool: string;
+    }>>;
+    estimateSessionFootprint(sessionKey: string): Promise<{
+        bytes: number;
+        tokens: number;
+    }>;
+    private estimateSessionBytesInFile;
+    /**
+     * Check if a file is a legacy flat transcript file (YYYY-MM-DD.jsonl format).
+     */
+    private isLegacyTranscriptFile;
+    /**
+     * Append a turn to the appropriate transcript file.
+     * Files are stored hierarchically: transcripts/{channelType}/{channelId}.jsonl
+     *
+     * Skips channel types in config.transcriptSkipChannelTypes (e.g., "cron").
+     */
+    append(entry: TranscriptEntry): Promise<void>;
+    /**
+     * Get all transcript files from the hierarchical directory structure.
+     * Recursively finds all .jsonl files in transcripts/{channelType}/{channelId}/ subdirectories.
+     */
+    private getAllTranscriptFiles;
+    /**
+     * Read transcript entries for a date range.
+     * Returns entries within the time range, optionally filtered by sessionKey.
+     * Reads from all channel subdirectories in the hierarchical structure.
+     */
+    readRange(startTime: string, endTime: string, sessionKey?: string): Promise<TranscriptEntry[]>;
+    /**
+     * Read the last N hours of transcript.
+     *
+     * Fast path: when sessionKey is given, reads only the 1-2 daily files for that
+     * specific channel instead of scanning all 95+ transcript files across all channels.
+     */
+    readRecent(hours: number, sessionKey?: string): Promise<TranscriptEntry[]>;
+    /**
+     * Optimized read for a specific session: only looks in that session's channel
+     * directory and only reads files whose date falls within the lookback window.
+     */
+    private readRecentForSession;
+    /**
+     * Cleanup old transcript entries that are older than retentionDays.
+     * For hierarchical structure, reads each file and rewrites without old entries.
+     * Legacy flat files are deleted if their date is older than retentionDays.
+     * Returns the number of files processed (cleaned or deleted).
+     */
+    cleanup(retentionDays: number): Promise<number>;
+    /**
+     * Clean up old entries from a single transcript file.
+     * Reads the file, filters out entries older than cutoff, and rewrites if needed.
+     * Returns true if the file was processed (cleaned or deleted).
+     */
+    private cleanupTranscriptFile;
+    /**
+     * Save a checkpoint to preserve conversation context.
+     * Called when compaction is detected.
+     */
+    saveCheckpoint(checkpoint: Checkpoint): Promise<void>;
+    /**
+     * Load a checkpoint if one exists and is not expired.
+     * Returns null if no checkpoint exists or if it has expired.
+     */
+    loadCheckpoint(sessionKey?: string): Promise<Checkpoint | null>;
+    /**
+     * Clear (delete) the checkpoint file.
+     * Called after successful injection of checkpoint context.
+     */
+    clearCheckpoint(): Promise<void>;
+    /**
+     * Format entries for recall injection.
+     * Returns a formatted string suitable for injecting into agent context.
+     *
+     * Format:
+     * ## Recent Conversation (last X hours)
+     * [10:32] User: message content
+     * [10:33] Assistant: response content
+     *
+     * Content is trimmed to approximately maxTokens.
+     */
+    formatForRecall(entries: TranscriptEntry[], maxTokens: number): string;
+    /**
+     * Create a checkpoint from the current buffer state.
+     * Helper method for creating checkpoints before compaction.
+     */
+    createCheckpoint(sessionKey: string, turns: TranscriptEntry[], ttlHours?: number): Checkpoint;
+    /**
+     * Get statistics about stored transcripts.
+     * Returns counts from the hierarchical directory structure.
+     */
+    getStats(): Promise<{
+        totalFiles: number;
+        totalEntries: number;
+        oldestFile: string | null;
+        newestFile: string | null;
+        channelTypes: Record<string, number>;
+    }>;
+    analyzeIntegrity(): Promise<SessionIntegrityReport>;
+    getRecoverySummary(sessionKey?: string): Promise<{
+        generatedAt: string;
+        sessionKey?: string;
+        healthy: boolean;
+        issueCount: number;
+        incompleteTurns: number;
+        brokenChains: number;
+        checkpointHealthy: boolean;
+    }>;
+}
+
+export { TranscriptManager };

package/dist/transcript.js

@@ -0,0 +1,9 @@
+import {
+  TranscriptManager
+} from "./chunk-UV2FO7J4.js";
+import "./chunk-YRMVARQP.js";
+import "./chunk-KWBU5S5U.js";
+export {
+  TranscriptManager
+};
+//# sourceMappingURL=transcript.js.map

package/dist/transcript.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/trust-zones.d.ts

@@ -0,0 +1,170 @@
+type TrustZoneName = "quarantine" | "working" | "trusted";
+type TrustZoneRecordKind = "memory" | "artifact" | "state" | "trajectory" | "external";
+type TrustZoneSourceClass = "tool_output" | "web_content" | "subagent_trace" | "system_memory" | "user_input" | "manual";
+declare function isTrustZoneName(value: string): value is TrustZoneName;
+interface TrustZoneProvenance {
+    sourceClass: TrustZoneSourceClass;
+    observedAt: string;
+    sessionKey?: string;
+    sourceId?: string;
+    evidenceHash?: string;
+}
+interface TrustZoneRecord {
+    schemaVersion: 1;
+    recordId: string;
+    zone: TrustZoneName;
+    recordedAt: string;
+    kind: TrustZoneRecordKind;
+    summary: string;
+    provenance: TrustZoneProvenance;
+    promotedFromZone?: TrustZoneName;
+    entityRefs?: string[];
+    tags?: string[];
+    metadata?: Record<string, string>;
+}
+type TrustZoneScoreBand = "low" | "medium" | "high";
+interface TrustZoneProvenanceScore {
+    total: number;
+    band: TrustZoneScoreBand;
+    anchored: boolean;
+    sourceClassWeight: number;
+    sourceIdBonus: number;
+    evidenceHashBonus: number;
+    sessionKeyBonus: number;
+}
+interface TrustZoneStoreStatus {
+    enabled: boolean;
+    promotionEnabled: boolean;
+    poisoningDefenseEnabled: boolean;
+    rootDir: string;
+    zonesDir: string;
+    records: {
+        total: number;
+        valid: number;
+        invalid: number;
+        byZone: Partial<Record<TrustZoneName, number>>;
+        byKind: Partial<Record<TrustZoneRecordKind, number>>;
+        latestRecordId?: string;
+        latestRecordedAt?: string;
+        latestZone?: TrustZoneName;
+        averageTrustScore?: number;
+        byTrustBand?: Partial<Record<TrustZoneScoreBand, number>>;
+    };
+    latestRecord?: TrustZoneRecord;
+    latestRecordTrustScore?: TrustZoneProvenanceScore;
+    invalidRecords: Array<{
+        path: string;
+        error: string;
+    }>;
+}
+interface TrustZonePromotionPlan {
+    allowed: boolean;
+    reasons: string[];
+    sourceRecordId: string;
+    sourceZone: TrustZoneName;
+    targetZone: TrustZoneName;
+    provenanceAnchored: boolean;
+}
+interface TrustZonePromotionResult {
+    plan: TrustZonePromotionPlan;
+    wroteRecord: boolean;
+    record: TrustZoneRecord;
+    filePath?: string;
+    sourceRecord: TrustZoneRecord;
+}
+interface TrustZoneSearchResult {
+    record: TrustZoneRecord;
+    score: number;
+    matchedFields: string[];
+}
+interface TrustZoneRecordEntry {
+    filePath: string;
+    record: TrustZoneRecord;
+}
+interface TrustZoneListResult {
+    total: number;
+    count: number;
+    limit: number;
+    offset: number;
+    records: TrustZoneRecordEntry[];
+    allRecords: TrustZoneRecord[];
+}
+interface TrustZonePromotionReadiness {
+    nextTargetZone?: TrustZoneName;
+    allowed: boolean;
+    reasons: string[];
+    requiresCorroboration: boolean;
+    corroborationCount: number;
+    corroborationSourceClasses: TrustZoneSourceClass[];
+}
+interface TrustZoneDemoSeedResult {
+    scenario: string;
+    dryRun: boolean;
+    recordsWritten: number;
+    records: TrustZoneRecord[];
+    filePaths: string[];
+}
+declare function resolveTrustZoneStoreDir(memoryDir: string, overrideDir?: string): string;
+declare function validateTrustZoneRecord(raw: unknown): TrustZoneRecord;
+declare function recordTrustZoneRecord(options: {
+    memoryDir: string;
+    trustZoneStoreDir?: string;
+    record: TrustZoneRecord;
+}): Promise<string>;
+declare function scoreTrustZoneProvenance(record: TrustZoneRecord): TrustZoneProvenanceScore;
+declare function planTrustZonePromotion(options: {
+    record: TrustZoneRecord;
+    targetZone: TrustZoneName;
+}): TrustZonePromotionPlan;
+declare function promoteTrustZoneRecord(options: {
+    memoryDir: string;
+    trustZoneStoreDir?: string;
+    enabled: boolean;
+    promotionEnabled: boolean;
+    poisoningDefenseEnabled?: boolean;
+    sourceRecordId: string;
+    targetZone: TrustZoneName;
+    recordedAt: string;
+    promotionReason: string;
+    summary?: string;
+    dryRun?: boolean;
+}): Promise<TrustZonePromotionResult>;
+declare function searchTrustZoneRecords(options: {
+    memoryDir: string;
+    trustZoneStoreDir?: string;
+    query: string;
+    maxResults: number;
+    sessionKey?: string;
+}): Promise<TrustZoneSearchResult[]>;
+declare function listTrustZoneRecords(options: {
+    memoryDir: string;
+    trustZoneStoreDir?: string;
+    query?: string;
+    zone?: TrustZoneName;
+    kind?: TrustZoneRecordKind;
+    sourceClass?: TrustZoneSourceClass;
+    limit?: number;
+    offset?: number;
+}): Promise<TrustZoneListResult>;
+declare function summarizeTrustZonePromotionReadiness(options: {
+    record: TrustZoneRecord;
+    allRecords: TrustZoneRecord[];
+    poisoningDefenseEnabled: boolean;
+}): TrustZonePromotionReadiness;
+declare function seedTrustZoneDemoDataset(options: {
+    memoryDir: string;
+    trustZoneStoreDir?: string;
+    enabled: boolean;
+    scenario?: string;
+    recordedAt?: string;
+    dryRun?: boolean;
+}): Promise<TrustZoneDemoSeedResult>;
+declare function getTrustZoneStoreStatus(options: {
+    memoryDir: string;
+    trustZoneStoreDir?: string;
+    enabled: boolean;
+    promotionEnabled: boolean;
+    poisoningDefenseEnabled: boolean;
+}): Promise<TrustZoneStoreStatus>;
+
+export { type TrustZoneDemoSeedResult, type TrustZoneListResult, type TrustZoneName, type TrustZonePromotionPlan, type TrustZonePromotionReadiness, type TrustZonePromotionResult, type TrustZoneProvenance, type TrustZoneProvenanceScore, type TrustZoneRecord, type TrustZoneRecordEntry, type TrustZoneRecordKind, type TrustZoneScoreBand, type TrustZoneSearchResult, type TrustZoneSourceClass, type TrustZoneStoreStatus, getTrustZoneStoreStatus, isTrustZoneName, listTrustZoneRecords, planTrustZonePromotion, promoteTrustZoneRecord, recordTrustZoneRecord, resolveTrustZoneStoreDir, scoreTrustZoneProvenance, searchTrustZoneRecords, seedTrustZoneDemoDataset, summarizeTrustZonePromotionReadiness, validateTrustZoneRecord };

package/dist/trust-zones.js

@@ -0,0 +1,32 @@
+import {
+  getTrustZoneStoreStatus,
+  isTrustZoneName,
+  listTrustZoneRecords,
+  planTrustZonePromotion,
+  promoteTrustZoneRecord,
+  recordTrustZoneRecord,
+  resolveTrustZoneStoreDir,
+  scoreTrustZoneProvenance,
+  searchTrustZoneRecords,
+  seedTrustZoneDemoDataset,
+  summarizeTrustZonePromotionReadiness,
+  validateTrustZoneRecord
+} from "./chunk-EQINRHYR.js";
+import "./chunk-DT5TVLJE.js";
+import "./chunk-DGXUHMOV.js";
+import "./chunk-LPSF4OQH.js";
+export {
+  getTrustZoneStoreStatus,
+  isTrustZoneName,
+  listTrustZoneRecords,
+  planTrustZonePromotion,
+  promoteTrustZoneRecord,
+  recordTrustZoneRecord,
+  resolveTrustZoneStoreDir,
+  scoreTrustZoneProvenance,
+  searchTrustZoneRecords,
+  seedTrustZoneDemoDataset,
+  summarizeTrustZonePromotionReadiness,
+  validateTrustZoneRecord
+};
+//# sourceMappingURL=trust-zones.js.map

package/dist/trust-zones.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}