@runcore-sh/runcore 0.3.1 → 0.4.0

package/dist/dictionary/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Dictionary Protocol — Shared types.
+ *
+ * The dictionary is the canonical set of specs, glossary, defaults, and protocols
+ * that define how Core works. Published via npm, synced by instances.
+ */
+/** A single spec entry in the dictionary. */
+export interface DictionarySpec {
+    name: string;
+    title: string;
+    status: string;
+    content: string;
+    checksum: string;
+}
+/** Glossary: canonical term definitions. */
+export type Glossary = Record<string, string>;
+/** Default configuration values recommended by the dictionary. */
+export interface DictionaryDefaults {
+    dehydration: {
+        quiet_threshold_multiplier: number;
+        stage_duration: string;
+        grace_period: string;
+    };
+    calibration: {
+        recalibration_interval_interactions: number;
+        recalibration_interval_ticks: number;
+    };
+    posture: {
+        board_decay_minutes: number;
+        pulse_decay_minutes: number;
+    };
+    pain: {
+        token_budget_warn: number;
+        error_spike_threshold: number;
+    };
+    [key: string]: Record<string, unknown>;
+}
+/** The full dictionary payload. */
+export interface Dictionary {
+    version: string;
+    publishedAt: string;
+    specs: DictionarySpec[];
+    glossary: Glossary;
+    defaults: DictionaryDefaults;
+}
+/** Local version tracking stored at brain/dictionary/version.json. */
+export interface DictionaryVersionFile {
+    version: string;
+    synced_at: string;
+}
+/** A changelog entry appended to brain/dictionary/changelog.jsonl. */
+export interface DictionaryChangelogEntry {
+    version: string;
+    timestamp: string;
+    specsAdded: string[];
+    specsUpdated: string[];
+    specsRemoved: string[];
+    summary: string;
+}
+/** Result of a sync check. */
+export interface SyncResult {
+    status: "updated" | "current" | "offline";
+    localVersion: string;
+    remoteVersion?: string;
+    changes?: DictionaryChangelogEntry;
+}
+/** Compatibility check result. */
+export interface CompatibilityResult {
+    compatible: boolean;
+    localVersion: string;
+    remoteVersion: string;
+    breakingChanges: string[];
+    warnings: string[];
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/dictionary/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,6CAA6C;AAC7C,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,4CAA4C;AAC5C,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE9C,kEAAkE;AAClE,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE;QACX,0BAA0B,EAAE,MAAM,CAAC;QACnC,cAAc,EAAE,MAAM,CAAC;QACvB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,WAAW,EAAE;QACX,mCAAmC,EAAE,MAAM,CAAC;QAC5C,4BAA4B,EAAE,MAAM,CAAC;KACtC,CAAC;IACF,OAAO,EAAE;QACP,mBAAmB,EAAE,MAAM,CAAC;QAC5B,mBAAmB,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF,IAAI,EAAE;QACJ,iBAAiB,EAAE,MAAM,CAAC;QAC1B,qBAAqB,EAAE,MAAM,CAAC;KAC/B,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED,mCAAmC;AACnC,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,EAAE,kBAAkB,CAAC;CAC9B;AAED,sEAAsE;AACtE,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,sEAAsE;AACtE,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,8BAA8B;AAC9B,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,wBAAwB,CAAC;CACpC;AAED,kCAAkC;AAClC,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB"}

package/dist/dictionary/types.js

@@ -0,0 +1,8 @@
+/**
+ * Dictionary Protocol — Shared types.
+ *
+ * The dictionary is the canonical set of specs, glossary, defaults, and protocols
+ * that define how Core works. Published via npm, synced by instances.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/dictionary/types.js.map

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

package/dist/dictionary/updater.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Dictionary Protocol — Update checker.
+ *
+ * Timer-based wrapper around DictionaryClient:
+ * - Boot sync on startup (forced check)
+ * - Periodic checks (configurable interval, default 24h)
+ * - Graceful offline handling
+ *
+ * Sidecar/timer pattern: module-level state, idempotent start/stop.
+ */
+import { DictionaryClient } from "./client.js";
+import type { SyncResult } from "./types.js";
+export interface DictionaryUpdaterConfig {
+    brainDir: string;
+    apiBase?: string;
+    checkIntervalMs?: number;
+}
+export declare function startDictionaryUpdater(config: DictionaryUpdaterConfig): Promise<SyncResult>;
+export declare function stopDictionaryUpdater(): void;
+export declare function isDictionaryUpdaterRunning(): boolean;
+export declare function getLastSyncResult(): SyncResult | null;
+export declare function getDictionaryClient(): DictionaryClient | null;
+//# sourceMappingURL=updater.d.ts.map

package/dist/dictionary/updater.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updater.d.ts","sourceRoot":"","sources":["../../src/dictionary/updater.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAO7C,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAuBD,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,UAAU,CAAC,CAqCrB;AAED,wBAAgB,qBAAqB,IAAI,IAAI,CAO5C;AAED,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD;AAED,wBAAgB,iBAAiB,IAAI,UAAU,GAAG,IAAI,CAErD;AAED,wBAAgB,mBAAmB,IAAI,gBAAgB,GAAG,IAAI,CAE7D"}

package/dist/dictionary/updater.js

@@ -0,0 +1,84 @@
+/**
+ * Dictionary Protocol — Update checker.
+ *
+ * Timer-based wrapper around DictionaryClient:
+ * - Boot sync on startup (forced check)
+ * - Periodic checks (configurable interval, default 24h)
+ * - Graceful offline handling
+ *
+ * Sidecar/timer pattern: module-level state, idempotent start/stop.
+ */
+import { DictionaryClient } from "./client.js";
+import { createLogger } from "../utils/logger.js";
+const log = createLogger("dictionary");
+const DEFAULT_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+let timer = null;
+let client = null;
+let lastResult = null;
+function logSyncResult(result, context) {
+    switch (result.status) {
+        case "updated":
+            log.info(`${context}: updated ${result.localVersion}`, {
+                remote: result.remoteVersion,
+                changes: result.changes?.summary,
+            });
+            break;
+        case "current":
+            log.info(`${context}: current at ${result.localVersion}`);
+            break;
+        case "offline":
+            log.warn(`${context}: offline — using cached dictionary ${result.localVersion}`);
+            break;
+    }
+}
+export async function startDictionaryUpdater(config) {
+    if (timer) {
+        return lastResult ?? { status: "current", localVersion: "0.0.0" };
+    }
+    client = new DictionaryClient({
+        brainDir: config.brainDir,
+        apiBase: config.apiBase,
+        syncIntervalMs: config.checkIntervalMs,
+    });
+    const bootResult = await client.bootSync();
+    lastResult = bootResult;
+    logSyncResult(bootResult, "Boot sync");
+    const interval = config.checkIntervalMs ??
+        (parseInt(process.env.DICTIONARY_CHECK_INTERVAL_MS ?? "", 10) || DEFAULT_CHECK_INTERVAL_MS);
+    timer = setInterval(async () => {
+        if (!client)
+            return;
+        try {
+            const result = await client.tickCheck();
+            lastResult = result;
+            if (result.status === "updated") {
+                logSyncResult(result, "Periodic sync");
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            log.warn(`Dictionary check failed: ${msg}`);
+        }
+    }, interval);
+    const hrs = Math.round(interval / 3_600_000);
+    log.info(`Dictionary updater started: checking every ${hrs}h`);
+    return bootResult;
+}
+export function stopDictionaryUpdater() {
+    if (timer) {
+        clearInterval(timer);
+        timer = null;
+    }
+    client = null;
+    lastResult = null;
+}
+export function isDictionaryUpdaterRunning() {
+    return timer !== null;
+}
+export function getLastSyncResult() {
+    return lastResult;
+}
+export function getDictionaryClient() {
+    return client;
+}
+//# sourceMappingURL=updater.js.map

package/dist/dictionary/updater.js.map

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

package/dist/dictionary/versioning.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Dictionary Protocol — Semantic versioning utilities.
+ */
+export interface SemverParts {
+    major: number;
+    minor: number;
+    patch: number;
+}
+export declare function parseSemver(version: string): SemverParts;
+export declare function formatSemver(parts: SemverParts): string;
+export declare function compareSemver(a: string, b: string): number;
+export declare function isValidSemver(version: string): boolean;
+export declare function getBumpType(from: string, to: string): "major" | "minor" | "patch" | "none" | "downgrade";
+export declare function bumpVersion(version: string, type: "major" | "minor" | "patch"): string;
+//# sourceMappingURL=versioning.d.ts.map

package/dist/dictionary/versioning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioning.d.ts","sourceRoot":"","sources":["../../src/dictionary/versioning.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CAMxD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAEvD;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,WAAW,CAUpD;AAED,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,GAChC,MAAM,CAUR"}

package/dist/dictionary/versioning.js

@@ -0,0 +1,52 @@
+/**
+ * Dictionary Protocol — Semantic versioning utilities.
+ */
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+export function parseSemver(version) {
+    if (!SEMVER_RE.test(version)) {
+        throw new Error(`Invalid semver: "${version}"`);
+    }
+    const [major, minor, patch] = version.split(".").map(Number);
+    return { major, minor, patch };
+}
+export function formatSemver(parts) {
+    return `${parts.major}.${parts.minor}.${parts.patch}`;
+}
+export function compareSemver(a, b) {
+    const pa = parseSemver(a);
+    const pb = parseSemver(b);
+    if (pa.major !== pb.major)
+        return pa.major - pb.major;
+    if (pa.minor !== pb.minor)
+        return pa.minor - pb.minor;
+    return pa.patch - pb.patch;
+}
+export function isValidSemver(version) {
+    return SEMVER_RE.test(version);
+}
+export function getBumpType(from, to) {
+    const diff = compareSemver(to, from);
+    if (diff === 0)
+        return "none";
+    if (diff < 0)
+        return "downgrade";
+    const f = parseSemver(from);
+    const t = parseSemver(to);
+    if (t.major > f.major)
+        return "major";
+    if (t.minor > f.minor)
+        return "minor";
+    return "patch";
+}
+export function bumpVersion(version, type) {
+    const parts = parseSemver(version);
+    switch (type) {
+        case "major":
+            return formatSemver({ major: parts.major + 1, minor: 0, patch: 0 });
+        case "minor":
+            return formatSemver({ major: parts.major, minor: parts.minor + 1, patch: 0 });
+        case "patch":
+            return formatSemver({ major: parts.major, minor: parts.minor, patch: parts.patch + 1 });
+    }
+}
+//# sourceMappingURL=versioning.js.map

package/dist/dictionary/versioning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioning.js","sourceRoot":"","sources":["../../src/dictionary/versioning.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,SAAS,GAAG,iBAAiB,CAAC;AAQpC,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,oBAAoB,OAAO,GAAG,CAAC,CAAC;IAClD,CAAC;IACD,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7D,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAkB;IAC7C,OAAO,GAAG,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,CAAS,EAAE,CAAS;IAChD,MAAM,EAAE,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;IAC1B,MAAM,EAAE,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;IAC1B,IAAI,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC;IACtD,IAAI,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC;IACtD,OAAO,EAAE,CAAC,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,OAAO,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,IAAY,EACZ,EAAU;IAEV,MAAM,IAAI,GAAG,aAAa,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACrC,IAAI,IAAI,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IAC9B,IAAI,IAAI,GAAG,CAAC;QAAE,OAAO,WAAW,CAAC;IAEjC,MAAM,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,CAAC,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;IAC1B,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK;QAAE,OAAO,OAAO,CAAC;IACtC,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK;QAAE,OAAO,OAAO,CAAC;IACtC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,OAAe,EACf,IAAiC;IAEjC,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACnC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,OAAO;YACV,OAAO,YAAY,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;QACtE,KAAK,OAAO;YACV,OAAO,YAAY,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;QAChF,KAAK,OAAO;YACV,OAAO,YAAY,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC;IAC5F,CAAC;AACH,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Structured error types for Core.
+ * Provides consistent error classification across the application.
+ */
+/** Base error for all Core subsystems. */
+export declare class CoreError extends Error {
+    readonly code: string;
+    readonly recoverable: boolean;
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, recoverable?: boolean, context?: Record<string, unknown> | undefined);
+}
+/** Error during file I/O operations (brain files, settings, etc.). */
+export declare class FileIOError extends CoreError {
+    readonly path: string;
+    readonly operation: "read" | "write" | "stat" | "access";
+    constructor(path: string, operation: "read" | "write" | "stat" | "access", cause: unknown);
+    get isNotFound(): boolean;
+    get isPermissionDenied(): boolean;
+    get isDiskFull(): boolean;
+}
+/** Error during configuration loading. */
+export declare class ConfigError extends CoreError {
+    readonly configName: string;
+    constructor(configName: string, message: string, cause?: unknown);
+}
+/** Error during agent process management. */
+export declare class AgentProcessError extends CoreError {
+    readonly pid?: number | undefined;
+    readonly taskId?: string | undefined;
+    constructor(message: string, pid?: number | undefined, taskId?: string | undefined, cause?: unknown);
+}
+/** Extract a human-readable message from any caught error value. */
+export declare function errorMessage(err: unknown): string;
+/** Extract the errno code from an error, if present. */
+export declare function errnoCode(err: unknown): string | undefined;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,0CAA0C;AAC1C,qBAAa,SAAU,SAAQ,KAAK;aAEhB,IAAI,EAAE,MAAM;aAEZ,WAAW,EAAE,OAAO;aACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAHjC,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM,EACC,WAAW,GAAE,OAAe,EAC5B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAKpD;AAED,sEAAsE;AACtE,qBAAa,WAAY,SAAQ,SAAS;aAEtB,IAAI,EAAE,MAAM;aACZ,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ;gBAD/C,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,EAC/D,KAAK,EAAE,OAAO;IAahB,IAAI,UAAU,IAAI,OAAO,CAAwC;IACjE,IAAI,kBAAkB,IAAI,OAAO,CAAsE;IACvG,IAAI,UAAU,IAAI,OAAO,CAAwC;CAClE;AAED,0CAA0C;AAC1C,qBAAa,WAAY,SAAQ,SAAS;aAEtB,UAAU,EAAE,MAAM;gBAAlB,UAAU,EAAE,MAAM,EAClC,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO;CAUlB;AAED,6CAA6C;AAC7C,qBAAa,iBAAkB,SAAQ,SAAS;aAG5B,GAAG,CAAC,EAAE,MAAM;aACZ,MAAM,CAAC,EAAE,MAAM;gBAF/B,OAAO,EAAE,MAAM,EACC,GAAG,CAAC,EAAE,MAAM,YAAA,EACZ,MAAM,CAAC,EAAE,MAAM,YAAA,EAC/B,KAAK,CAAC,EAAE,OAAO;CAUlB;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAIjD;AAED,wDAAwD;AACxD,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAE1D"}

package/dist/errors.js

@@ -0,0 +1,66 @@
+/**
+ * Structured error types for Core.
+ * Provides consistent error classification across the application.
+ */
+/** Base error for all Core subsystems. */
+export class CoreError extends Error {
+    code;
+    recoverable;
+    context;
+    constructor(code, message, recoverable = false, context) {
+        super(message);
+        this.code = code;
+        this.recoverable = recoverable;
+        this.context = context;
+        this.name = "CoreError";
+    }
+}
+/** Error during file I/O operations (brain files, settings, etc.). */
+export class FileIOError extends CoreError {
+    path;
+    operation;
+    constructor(path, operation, cause) {
+        const errMsg = cause instanceof Error ? cause.message : String(cause);
+        const errCode = cause?.code;
+        super(errCode ? `FILE_${errCode}` : "FILE_IO_ERROR", `Failed to ${operation} ${path}: ${errMsg}`, errCode === "ENOENT" || errCode === "EPIPE", { path, operation, errno: errCode });
+        this.path = path;
+        this.operation = operation;
+        this.name = "FileIOError";
+    }
+    get isNotFound() { return this.code === "FILE_ENOENT"; }
+    get isPermissionDenied() { return this.code === "FILE_EACCES" || this.code === "FILE_EPERM"; }
+    get isDiskFull() { return this.code === "FILE_ENOSPC"; }
+}
+/** Error during configuration loading. */
+export class ConfigError extends CoreError {
+    configName;
+    constructor(configName, message, cause) {
+        super("CONFIG_ERROR", `${configName}: ${message}`, true, { configName, cause: cause instanceof Error ? cause.message : cause });
+        this.configName = configName;
+        this.name = "ConfigError";
+    }
+}
+/** Error during agent process management. */
+export class AgentProcessError extends CoreError {
+    pid;
+    taskId;
+    constructor(message, pid, taskId, cause) {
+        super("AGENT_PROCESS_ERROR", message, false, { pid, taskId, cause: cause instanceof Error ? cause.message : cause });
+        this.pid = pid;
+        this.taskId = taskId;
+        this.name = "AgentProcessError";
+    }
+}
+/** Extract a human-readable message from any caught error value. */
+export function errorMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === "string")
+        return err;
+    return String(err);
+}
+/** Extract the errno code from an error, if present. */
+export function errnoCode(err) {
+    return err?.code;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/events/event-bus.d.ts

@@ -0,0 +1,37 @@
+/**
+ * EventBus — typed pub/sub for system-wide communication.
+ *
+ * Two implementations:
+ * - EventBus: simple, lightweight, no frills
+ * - ManagedEventBus: filters, max invocations, subscription IDs, async emit
+ */
+import type { EventHandler, EventMap, Subscription, EventSubscription, EventBusInterface, SubscribeOptions } from "./types.js";
+export declare class EventBus implements EventBusInterface {
+    private readonly handlers;
+    subscribe<K extends keyof EventMap & string>(eventType: K, handler: EventHandler<EventMap[K]>): Subscription;
+    unsubscribe<K extends keyof EventMap & string>(eventType: K, handler: EventHandler<EventMap[K]>): void;
+    emit<K extends keyof EventMap & string>(eventType: K, data: EventMap[K], source?: string): void;
+    clear(eventType?: string): void;
+    listenerCount(eventType: string): number;
+    private dispatch;
+}
+export declare class ManagedEventBus implements EventBusInterface {
+    private readonly subscriptions;
+    private readonly subscriptionIndex;
+    private errorHandler;
+    subscribe<K extends keyof EventMap & string>(eventType: K, handler: EventHandler<EventMap[K]>, options?: SubscribeOptions<EventMap[K]>): EventSubscription;
+    once<K extends keyof EventMap & string>(eventType: K, handler: EventHandler<EventMap[K]>, options?: Omit<SubscribeOptions<EventMap[K]>, "maxInvocations">): EventSubscription;
+    unsubscribe<K extends keyof EventMap & string>(eventType: K, handler: EventHandler<EventMap[K]>): void;
+    emit<K extends keyof EventMap & string>(eventType: K, data: EventMap[K], source?: string): void;
+    emitAsync<K extends keyof EventMap & string>(eventType: K, data: EventMap[K], source?: string): Promise<void>;
+    clear(eventType?: string): void;
+    listenerCount(eventType: string): number;
+    getSubscriptions(eventType?: string): readonly EventSubscription[];
+    onError(handler: (eventType: string, error: unknown) => void): void;
+    destroy(): void;
+    private dispatch;
+    private dispatchAsync;
+    private removeSubscription;
+    private handleError;
+}
+//# sourceMappingURL=event-bus.d.ts.map

package/dist/events/event-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/events/event-bus.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAEV,YAAY,EACZ,QAAQ,EACR,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EAEjB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAIpB,qBAAa,QAAS,YAAW,iBAAiB;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6C;IAEtE,SAAS,CAAC,CAAC,SAAS,MAAM,QAAQ,GAAG,MAAM,EACzC,SAAS,EAAE,CAAC,EACZ,OAAO,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GACjC,YAAY;IAQf,WAAW,CAAC,CAAC,SAAS,MAAM,QAAQ,GAAG,MAAM,EAC3C,SAAS,EAAE,CAAC,EACZ,OAAO,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GACjC,IAAI;IAOP,IAAI,CAAC,CAAC,SAAS,MAAM,QAAQ,GAAG,MAAM,EACpC,SAAS,EAAE,CAAC,EACZ,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI;IAYP,KAAK,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ/B,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAIxC,OAAO,CAAC,QAAQ;CAgBjB;AAeD,qBAAa,eAAgB,YAAW,iBAAiB;IACvD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6C;IAC3E,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA2C;IAC7E,OAAO,CAAC,YAAY,CAA8D;IAElF,SAAS,CAAC,CAAC,SAAS,MAAM,QAAQ,GAAG,MAAM,EACzC,SAAS,EAAE,CAAC,EACZ,OAAO,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAClC,OAAO,CAAC,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GACtC,iBAAiB;IA2BpB,IAAI,CAAC,CAAC,SAAS,MAAM,QAAQ,GAAG,MAAM,EACpC,SAAS,EAAE,CAAC,EACZ,OAAO,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAClC,OAAO,CAAC,EAAE,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,gBAAgB,CAAC,GAC9D,iBAAiB;IAIpB,WAAW,CAAC,CAAC,SAAS,MAAM,QAAQ,GAAG,MAAM,EAC3C,SAAS,EAAE,CAAC,EACZ,OAAO,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GACjC,IAAI;IAOP,IAAI,CAAC,CAAC,SAAS,MAAM,QAAQ,GAAG,MAAM,EACpC,SAAS,EAAE,CAAC,EACZ,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI;IAWD,SAAS,CAAC,CAAC,SAAS,MAAM,QAAQ,GAAG,MAAM,EAC/C,SAAS,EAAE,CAAC,EACZ,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC;IAyBhB,KAAK,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IAmB/B,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAIxC,gBAAgB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,iBAAiB,EAAE;IAclE,OAAO,CAAC,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI;IAInE,OAAO,IAAI,IAAI;IAKf,OAAO,CAAC,QAAQ;IA+BhB,OAAO,CAAC,aAAa;IA0BrB,OAAO,CAAC,kBAAkB;IAa1B,OAAO,CAAC,WAAW;CAOpB"}