@lovelybunch/core 1.0.66 → 1.0.68

package/dist/logging/kinds.js

@@ -0,0 +1,207 @@
+/**
+ * Event kind taxonomy for Coconut activity logging
+ * @module logging/kinds
+ *
+ * Event kinds follow a hierarchical naming convention:
+ * {entity}.{action}.{qualifier}
+ *
+ * Examples:
+ * - proposal.create
+ * - agent.session.start
+ * - code.commit
+ */
+/**
+ * Proposal-related events
+ */
+export const ProposalKinds = {
+    CREATE: "proposal.create",
+    UPDATE: "proposal.update",
+    RUN_START: "proposal.run.start",
+    RUN_END: "proposal.run.end",
+    STATUS_CHANGE: "proposal.status.change",
+};
+/**
+ * Agent and session events
+ */
+export const AgentKinds = {
+    SESSION_START: "agent.session.start",
+    SESSION_STDOUT: "agent.session.stdout",
+    SESSION_END: "agent.session.end",
+    SESSION_ERROR: "agent.session.error",
+};
+/**
+ * Code and git-related events
+ */
+export const CodeKinds = {
+    EDIT: "code.edit",
+    COMMIT: "code.commit",
+    BRANCH_CREATE: "code.branch.create",
+    WORKTREE_ADD: "code.worktree.add",
+};
+/**
+ * Knowledge base events
+ */
+export const KnowledgeKinds = {
+    CREATE: "knowledge.create",
+    UPDATE: "knowledge.update",
+    DELETE: "knowledge.delete",
+};
+/**
+ * Job scheduling and execution events
+ */
+export const JobKinds = {
+    SCHEDULE: "job.schedule",
+    RUN_START: "job.run.start",
+    RUN_END: "job.run.end",
+    RUN_ERROR: "job.run.error",
+};
+/**
+ * Resource management events
+ */
+export const ResourceKinds = {
+    UPLOAD: "resource.upload",
+    DELETE: "resource.delete",
+};
+/**
+ * Authentication events (when auth is enabled)
+ */
+export const AuthKinds = {
+    LOGIN: "auth.login",
+    LOGOUT: "auth.logout",
+    API_KEY_USE: "auth.api.key.use",
+    API_KEY_CREATE: "auth.api.key.create",
+    API_KEY_DELETE: "auth.api.key.delete",
+};
+/**
+ * All event kinds in a single object
+ */
+export const EventKinds = {
+    ...ProposalKinds,
+    ...AgentKinds,
+    ...CodeKinds,
+    ...KnowledgeKinds,
+    ...JobKinds,
+    ...ResourceKinds,
+    ...AuthKinds,
+};
+/**
+ * Helper to validate if a string is a known event kind
+ */
+export function isValidEventKind(kind) {
+    return Object.values(EventKinds).includes(kind);
+}
+/**
+ * Registry of event kinds with metadata
+ * Useful for documentation and validation
+ */
+export const EventKindRegistry = {
+    [ProposalKinds.CREATE]: {
+        description: "A new change proposal was created",
+        tags: ["proposal"],
+    },
+    [ProposalKinds.UPDATE]: {
+        description: "A change proposal was updated",
+        tags: ["proposal"],
+    },
+    [ProposalKinds.RUN_START]: {
+        description: "Implementation of a proposal started",
+        tags: ["proposal", "execution"],
+    },
+    [ProposalKinds.RUN_END]: {
+        description: "Implementation of a proposal completed",
+        tags: ["proposal", "execution"],
+    },
+    [ProposalKinds.STATUS_CHANGE]: {
+        description: "Proposal status changed",
+        tags: ["proposal"],
+    },
+    [AgentKinds.SESSION_START]: {
+        description: "Agent session started",
+        tags: ["agent", "session"],
+    },
+    [AgentKinds.SESSION_STDOUT]: {
+        description: "Agent session output",
+        tags: ["agent", "session"],
+    },
+    [AgentKinds.SESSION_END]: {
+        description: "Agent session ended",
+        tags: ["agent", "session"],
+    },
+    [AgentKinds.SESSION_ERROR]: {
+        description: "Agent session encountered an error",
+        tags: ["agent", "session", "error"],
+    },
+    [CodeKinds.EDIT]: {
+        description: "Code was edited",
+        tags: ["code"],
+    },
+    [CodeKinds.COMMIT]: {
+        description: "Git commit was created",
+        tags: ["code", "git"],
+    },
+    [CodeKinds.BRANCH_CREATE]: {
+        description: "Git branch was created",
+        tags: ["code", "git"],
+    },
+    [CodeKinds.WORKTREE_ADD]: {
+        description: "Git worktree was added",
+        tags: ["code", "git"],
+    },
+    [KnowledgeKinds.CREATE]: {
+        description: "Knowledge base entry created",
+        tags: ["knowledge"],
+    },
+    [KnowledgeKinds.UPDATE]: {
+        description: "Knowledge base entry updated",
+        tags: ["knowledge"],
+    },
+    [KnowledgeKinds.DELETE]: {
+        description: "Knowledge base entry deleted",
+        tags: ["knowledge"],
+    },
+    [JobKinds.SCHEDULE]: {
+        description: "Job was scheduled",
+        tags: ["job"],
+    },
+    [JobKinds.RUN_START]: {
+        description: "Job run started",
+        tags: ["job", "execution"],
+    },
+    [JobKinds.RUN_END]: {
+        description: "Job run completed",
+        tags: ["job", "execution"],
+    },
+    [JobKinds.RUN_ERROR]: {
+        description: "Job run failed with error",
+        tags: ["job", "execution", "error"],
+    },
+    [ResourceKinds.UPLOAD]: {
+        description: "Resource was uploaded",
+        tags: ["resource"],
+    },
+    [ResourceKinds.DELETE]: {
+        description: "Resource was deleted",
+        tags: ["resource"],
+    },
+    [AuthKinds.LOGIN]: {
+        description: "User logged in",
+        tags: ["auth"],
+    },
+    [AuthKinds.LOGOUT]: {
+        description: "User logged out",
+        tags: ["auth"],
+    },
+    [AuthKinds.API_KEY_USE]: {
+        description: "API key was used for authentication",
+        tags: ["auth", "api"],
+    },
+    [AuthKinds.API_KEY_CREATE]: {
+        description: "API key was created",
+        tags: ["auth", "api"],
+    },
+    [AuthKinds.API_KEY_DELETE]: {
+        description: "API key was deleted",
+        tags: ["auth", "api"],
+    },
+};
+//# sourceMappingURL=kinds.js.map

package/dist/logging/kinds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kinds.js","sourceRoot":"","sources":["../../src/logging/kinds.ts"],"names":[],"mappings":"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"}

package/dist/logging/logger.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Logger facade for Coconut activity logging
+ * @module logging/logger
+ */
+import type { Logger, LoggerOptions } from "./types";
+/**
+ * Get or create the global logger instance
+ *
+ * This function returns a singleton logger that can be used throughout the application.
+ * The logger automatically fills in system fields (v, seq, ts, coconut) and applies
+ * redaction to scrub sensitive data.
+ *
+ * @param opts - Logger configuration options (only used on first call)
+ * @returns Logger instance
+ *
+ * @example
+ * ```typescript
+ * import { getLogger } from "@lovelybunch/core/logging/logger";
+ *
+ * const logger = getLogger();
+ * logger.log({
+ *   kind: "proposal.create",
+ *   actor: "human:sarah@company.com",
+ *   subject: "proposal:cp-123",
+ *   tags: ["proposal"],
+ *   payload: { intent: "Add dark mode" }
+ * });
+ * ```
+ */
+export declare function getLogger(opts?: Partial<LoggerOptions>): Logger;
+/**
+ * Reset the singleton logger (primarily for testing)
+ */
+export declare function resetLogger(): void;
+/**
+ * Check if a logger instance exists
+ */
+export declare function hasLogger(): boolean;
+export type { LogEventBase, Logger, LoggerOptions, LogLevel } from "./types";
+export { EventKinds } from "./kinds.js";
+export { defaultRedactor, createRedactor, noRedactor } from "./redact.js";
+//# sourceMappingURL=logger.d.ts.map

package/dist/logging/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logging/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAgB,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAOnE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,SAAS,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,MAAM,CAwC/D;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAKlC;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAEnC;AAGD,YAAY,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}

package/dist/logging/logger.js

@@ -0,0 +1,85 @@
+/**
+ * Logger facade for Coconut activity logging
+ * @module logging/logger
+ */
+import path from "node:path";
+import { JsonlWriter } from "./jsonl-writer.js";
+import { defaultRedactor } from "./redact.js";
+/**
+ * Singleton logger instance
+ */
+let singleton = null;
+/**
+ * Get or create the global logger instance
+ *
+ * This function returns a singleton logger that can be used throughout the application.
+ * The logger automatically fills in system fields (v, seq, ts, coconut) and applies
+ * redaction to scrub sensitive data.
+ *
+ * @param opts - Logger configuration options (only used on first call)
+ * @returns Logger instance
+ *
+ * @example
+ * ```typescript
+ * import { getLogger } from "@lovelybunch/core/logging/logger";
+ *
+ * const logger = getLogger();
+ * logger.log({
+ *   kind: "proposal.create",
+ *   actor: "human:sarah@company.com",
+ *   subject: "proposal:cp-123",
+ *   tags: ["proposal"],
+ *   payload: { intent: "Add dark mode" }
+ * });
+ * ```
+ */
+export function getLogger(opts) {
+    if (singleton) {
+        return singleton;
+    }
+    // Resolve configuration with defaults
+    const coconutId = opts?.coconutId ?? process.env.COCONUT_ID ?? "unknown.coconut";
+    const logsDir = opts?.logsDir ?? path.resolve(".nut/logs");
+    const rotateBytes = opts?.rotateBytes ?? 128 * 1024 * 1024; // 128MB default
+    const redactor = opts?.redactor ?? defaultRedactor;
+    // Create the JSONL writer
+    const writer = new JsonlWriter(logsDir, coconutId, rotateBytes);
+    // Create and cache the logger instance
+    singleton = {
+        log(event) {
+            // Apply redaction to the event
+            const sanitized = redactor(event);
+            // Auto-fill system fields and enqueue
+            writer.nextEvent(sanitized);
+        },
+        async flush() {
+            return writer.flush();
+        },
+        getSeq() {
+            return writer.getSeq();
+        },
+        async close() {
+            await writer.close();
+            singleton = null;
+        },
+    };
+    return singleton;
+}
+/**
+ * Reset the singleton logger (primarily for testing)
+ */
+export function resetLogger() {
+    if (singleton) {
+        void singleton.close();
+    }
+    singleton = null;
+}
+/**
+ * Check if a logger instance exists
+ */
+export function hasLogger() {
+    return singleton !== null;
+}
+export { EventKinds } from "./kinds.js";
+export { defaultRedactor, createRedactor, noRedactor } from "./redact.js";
+//# sourceMappingURL=logger.js.map

package/dist/logging/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/logging/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C;;GAEG;AACH,IAAI,SAAS,GAAkB,IAAI,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,SAAS,CAAC,IAA6B;IACrD,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,sCAAsC;IACtC,MAAM,SAAS,GACb,IAAI,EAAE,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,iBAAiB,CAAC;IACjE,MAAM,OAAO,GAAG,IAAI,EAAE,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC3D,MAAM,WAAW,GAAG,IAAI,EAAE,WAAW,IAAI,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,gBAAgB;IAC5E,MAAM,QAAQ,GAAG,IAAI,EAAE,QAAQ,IAAI,eAAe,CAAC;IAEnD,0BAA0B;IAC1B,MAAM,MAAM,GAAG,IAAI,WAAW,CAAC,OAAO,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;IAEhE,uCAAuC;IACvC,SAAS,GAAG;QACV,GAAG,CAAC,KAAmB;YACrB,+BAA+B;YAC/B,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;YAElC,sCAAsC;YACtC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QAC9B,CAAC;QAED,KAAK,CAAC,KAAK;YACT,OAAO,MAAM,CAAC,KAAK,EAAE,CAAC;QACxB,CAAC;QAED,MAAM;YACJ,OAAO,MAAM,CAAC,MAAM,EAAE,CAAC;QACzB,CAAC;QAED,KAAK,CAAC,KAAK;YACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YACrB,SAAS,GAAG,IAAI,CAAC;QACnB,CAAC;KACF,CAAC;IAEF,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW;IACzB,IAAI,SAAS,EAAE,CAAC;QACd,KAAK,SAAS,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;IACD,SAAS,GAAG,IAAI,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS;IACvB,OAAO,SAAS,KAAK,IAAI,CAAC;AAC5B,CAAC;AAID,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}

package/dist/logging/redact.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Payload redaction utilities for scrubbing sensitive data from log events
+ * @module logging/redact
+ */
+import type { LogEventBase } from "./types";
+/**
+ * Default redactor function that scrubs sensitive data from log events
+ *
+ * This function:
+ * - Removes sensitive fields from the payload
+ * - Redacts known patterns (API keys, tokens, etc.)
+ * - Preserves the overall structure of the event
+ *
+ * @param event - The log event to redact
+ * @returns A new event with sensitive data removed
+ */
+export declare function defaultRedactor(event: LogEventBase): LogEventBase;
+/**
+ * Create a custom redactor that combines the default redactor with additional rules
+ *
+ * @param additionalRedactor - Custom redaction function to apply after default redaction
+ * @returns Combined redactor function
+ */
+export declare function createRedactor(additionalRedactor?: (event: LogEventBase) => LogEventBase): (event: LogEventBase) => LogEventBase;
+/**
+ * No-op redactor that returns the event unchanged
+ * Useful for testing or when redaction is not needed
+ */
+export declare function noRedactor(event: LogEventBase): LogEventBase;
+//# sourceMappingURL=redact.d.ts.map

package/dist/logging/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../src/logging/redact.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAsG5C;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,CAqBjE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,YAAY,GACzD,CAAC,KAAK,EAAE,YAAY,KAAK,YAAY,CASvC;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,CAE5D"}

package/dist/logging/redact.js

@@ -0,0 +1,145 @@
+/**
+ * Payload redaction utilities for scrubbing sensitive data from log events
+ * @module logging/redact
+ */
+/**
+ * List of field names that commonly contain sensitive data
+ */
+const SENSITIVE_FIELD_NAMES = [
+    "password",
+    "passwordHash",
+    "secret",
+    "apiKey",
+    "api_key",
+    "token",
+    "accessToken",
+    "access_token",
+    "refreshToken",
+    "refresh_token",
+    "clientSecret",
+    "client_secret",
+    "privateKey",
+    "private_key",
+    "authorization",
+    "cookie",
+    "sessionSecret",
+    "session_secret",
+];
+/**
+ * Regular expressions to detect sensitive data patterns
+ */
+const SENSITIVE_PATTERNS = [
+    /sk-[a-zA-Z0-9]{20,}/g, // OpenAI API keys
+    /sk_live_[a-zA-Z0-9]{20,}/g, // Stripe live keys
+    /sk_test_[a-zA-Z0-9]{20,}/g, // Stripe test keys
+    /ghp_[a-zA-Z0-9]{36}/g, // GitHub personal access tokens
+    /gho_[a-zA-Z0-9]{36}/g, // GitHub OAuth tokens
+    /Bearer\s+[a-zA-Z0-9\-._~+/]+=*/g, // Bearer tokens
+];
+/**
+ * Placeholder text for redacted content
+ */
+const REDACTED = "[REDACTED]";
+/**
+ * Check if a field name is sensitive
+ */
+function isSensitiveFieldName(fieldName) {
+    const lowerField = fieldName.toLowerCase();
+    return SENSITIVE_FIELD_NAMES.some((sensitive) => lowerField.includes(sensitive.toLowerCase()));
+}
+/**
+ * Recursively redact sensitive fields from an object
+ */
+function redactObject(obj, depth = 0) {
+    // Prevent infinite recursion
+    if (depth > 10) {
+        return obj;
+    }
+    if (obj === null || obj === undefined) {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => redactObject(item, depth + 1));
+    }
+    if (typeof obj === "object") {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            if (isSensitiveFieldName(key)) {
+                result[key] = REDACTED;
+            }
+            else if (typeof value === "string") {
+                result[key] = redactString(value);
+            }
+            else {
+                result[key] = redactObject(value, depth + 1);
+            }
+        }
+        return result;
+    }
+    if (typeof obj === "string") {
+        return redactString(obj);
+    }
+    return obj;
+}
+/**
+ * Redact sensitive patterns from a string
+ */
+function redactString(str) {
+    let result = str;
+    for (const pattern of SENSITIVE_PATTERNS) {
+        result = result.replace(pattern, REDACTED);
+    }
+    return result;
+}
+/**
+ * Default redactor function that scrubs sensitive data from log events
+ *
+ * This function:
+ * - Removes sensitive fields from the payload
+ * - Redacts known patterns (API keys, tokens, etc.)
+ * - Preserves the overall structure of the event
+ *
+ * @param event - The log event to redact
+ * @returns A new event with sensitive data removed
+ */
+export function defaultRedactor(event) {
+    const redacted = {
+        ...event,
+    };
+    // Redact the payload if present
+    if (event.payload) {
+        redacted.payload = redactObject(event.payload);
+    }
+    // Redact actor field if it looks like an email with sensitive content
+    if (event.actor && typeof event.actor === "string") {
+        redacted.actor = redactString(event.actor);
+    }
+    // Redact subject field if needed
+    if (event.subject && typeof event.subject === "string") {
+        redacted.subject = redactString(event.subject);
+    }
+    return redacted;
+}
+/**
+ * Create a custom redactor that combines the default redactor with additional rules
+ *
+ * @param additionalRedactor - Custom redaction function to apply after default redaction
+ * @returns Combined redactor function
+ */
+export function createRedactor(additionalRedactor) {
+    if (!additionalRedactor) {
+        return defaultRedactor;
+    }
+    return (event) => {
+        const defaultRedacted = defaultRedactor(event);
+        return additionalRedactor(defaultRedacted);
+    };
+}
+/**
+ * No-op redactor that returns the event unchanged
+ * Useful for testing or when redaction is not needed
+ */
+export function noRedactor(event) {
+    return event;
+}
+//# sourceMappingURL=redact.js.map

package/dist/logging/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../../src/logging/redact.ts"],"names":[],"mappings":"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"}

package/dist/logging/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Core logging types for Coconut activity logging system
+ * @module logging/types
+ */
+/**
+ * Log level enumeration
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Base event structure for logging
+ * All events share these common fields, with additional payload data specific to the event type
+ */
+export interface LogEventBase {
+    /** Optional tenant identifier for multi-tenant deployments */
+    tenant?: string;
+    /** Event kind/type from the taxonomy (e.g., "proposal.create", "agent.session.start") */
+    kind: string;
+    /** Actor performing the action (e.g., "human:email@example.com", "agent:coder") */
+    actor?: string;
+    /** Subject entity this event is about (e.g., "proposal:cp-123", "session:abc123") */
+    subject?: string;
+    /** Correlation ID for tracing related events across operations */
+    trace?: string;
+    /** Optional parent trace hop for nested operations */
+    parent?: string;
+    /** Event severity level */
+    level?: LogLevel;
+    /** Queryable tags for filtering and categorization */
+    tags?: string[];
+    /** Event-specific payload data */
+    payload?: unknown;
+    /** Override timestamp (primarily for backfilling historical data) */
+    ts?: string;
+}
+/**
+ * Complete event structure with system-filled fields
+ */
+export interface LogEvent extends Omit<LogEventBase, 'ts'> {
+    /** Schema version for the event format */
+    v: number;
+    /** Monotonic sequence number within this Coconut instance */
+    seq: number;
+    /** ISO 8601 timestamp (required in final event) */
+    ts: string;
+    /** Stable Coconut instance identifier */
+    coconut: string;
+}
+/**
+ * Configuration options for the logger
+ */
+export interface LoggerOptions {
+    /** Unique identifier for this Coconut instance */
+    coconutId: string;
+    /** Directory where log files are stored (default: ".nut/logs") */
+    logsDir?: string;
+    /** File size threshold for rotation in bytes (default: 128MB) */
+    rotateBytes?: number;
+    /** Optional redaction function to scrub sensitive data from payloads */
+    redactor?: (event: LogEventBase) => LogEventBase;
+}
+/**
+ * Logger interface for emitting events
+ */
+export interface Logger {
+    /** Enqueue an event for writing (non-blocking) */
+    log(event: LogEventBase): void;
+    /** Flush pending events to disk (best-effort fsync) */
+    flush(): Promise<void>;
+    /** Get the last assigned sequence number */
+    getSeq(): number;
+    /** Close the logger and cleanup resources */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/logging/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/logging/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;IAEb,mFAAmF;IACnF,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,QAAQ,CAAC;IAEjB,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB,kCAAkC;IAClC,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,qEAAqE;IACrE,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,QAAS,SAAQ,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC;IACxD,0CAA0C;IAC1C,CAAC,EAAE,MAAM,CAAC;IAEV,6DAA6D;IAC7D,GAAG,EAAE,MAAM,CAAC;IAEZ,mDAAmD;IACnD,EAAE,EAAE,MAAM,CAAC;IAEX,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAElB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,YAAY,CAAC;CAClD;AAED;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,kDAAkD;IAClD,GAAG,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IAE/B,uDAAuD;IACvD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB,4CAA4C;IAC5C,MAAM,IAAI,MAAM,CAAC;IAEjB,6CAA6C;IAC7C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}

package/dist/logging/types.js

@@ -0,0 +1,6 @@
+/**
+ * Core logging types for Coconut activity logging system
+ * @module logging/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/logging/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/logging/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovelybunch/core",
-  "version": "1.0.66",
+  "version": "1.0.68",
   "description": "Core Coconut functionality",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,6 +9,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./logging": {
+      "types": "./dist/logging/index.d.ts",
+      "import": "./dist/logging/index.js"
     }
   },
   "files": [
@@ -31,7 +35,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@lovelybunch/types": "^1.0.66",
+    "@lovelybunch/types": "^1.0.68",
     "gray-matter": "^4.0.3",
     "fuse.js": "^7.0.0",
     "nanoid": "^5.0.6"

package/dist/workflow-templates.d.ts

@@ -1,6 +0,0 @@
-/**
- * Built-in workflow templates
- * These are created in .nut/agents/workflows/ during nut init
- */
-export declare const workflowTemplates: Record<string, string>;
-//# sourceMappingURL=workflow-templates.d.ts.map

package/dist/workflow-templates.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"workflow-templates.d.ts","sourceRoot":"","sources":["../src/workflow-templates.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAyDpD,CAAC"}