catui-agent 1.0.0-beta.0

package/dist/packages/mem-core/src/store.js

@@ -0,0 +1 @@
+var y=Object.defineProperty;var r=(t,n)=>y(t,"name",{value:n,configurable:!0});import{existsSync as f}from"node:fs";import{mkdir as w,readdir as g,readFile as h,writeFile as x}from"node:fs/promises";import{dirname as j,join as l}from"node:path";async function c(t){f(t)||await w(t,{recursive:!0})}r(c,"ensureDir");async function a(t,n){try{if(!f(t))return n;const e=await h(t,"utf-8");return JSON.parse(e)}catch{return n}}r(a,"readJson");async function u(t,n){await c(j(t)),await x(t,JSON.stringify(n,null,2),"utf-8")}r(u,"writeJson");function m(t){if(!t)return"untitled";const e=t.split(/\s+/).filter(i=>i.length>0).slice(0,5).join(" ");return e.length>30?`${e.slice(0,27)}...`:e||"untitled"}r(m,"deriveNameFromContent");function p(t){if(!t)return"";if(t.length<=150)return t;const n=t.slice(0,160).search(/[。.!！?？]\s*/);return n>50?t.slice(0,n+1):`${t.slice(0,147)}...`}r(p,"deriveSummaryFromContent");function E(t){if(t.name&&t.summary)return t;const n=t.content||t.detail||"";return{...t,name:t.name||m(n),summary:t.summary||p(n),detail:t.detail||n}}r(E,"migrateEntry");async function k(t){const n=await a(t,[]);return Array.isArray(n)?n.filter(v).map(E):[]}r(k,"loadEntries");function v(t){if(typeof t!="object"||t===null)return!1;const n=t;return typeof n.id=="string"&&typeof n.type=="string"&&Array.isArray(n.tags)&&typeof n.project=="string"&&typeof n.importance=="number"&&typeof n.created=="string"&&typeof n.accessCount=="number"}r(v,"isMemoryEntryLike");async function C(t,n,e,i){n.length>e&&(n.sort((o,d)=>i(d)-i(o)),n.length=e);const s=n.map(o=>({...o,content:o.detail||o.content||o.summary||""}));await u(t,s)}r(C,"saveEntries");async function N(t){await c(t);const n=await g(t),e=[];for(const i of n){if(!i.endsWith(".json"))continue;const s=await a(l(t,i),null);s&&e.push(s)}return e}r(N,"loadEpisodes");async function W(t,n){await c(t),await u(l(t,`${n.date}-${n.sessionId.slice(0,8)}.json`),n)}r(W,"saveEpisode");async function b(t){return a(t,[])}r(b,"loadWork");async function F(t,n,e,i){n.length>e&&(n.sort((s,o)=>i(o)-i(s)),n.length=e),await u(t,n)}r(F,"saveWork");async function M(t){return a(t,{totalSessions:0,version:1})}r(M,"loadMeta");export{m as deriveNameFromContent,p as deriveSummaryFromContent,k as loadEntries,N as loadEpisodes,M as loadMeta,b as loadWork,a as readJson,C as saveEntries,W as saveEpisode,F as saveWork,u as writeJson};

package/dist/packages/mem-core/src/types.d.ts

@@ -0,0 +1,329 @@
+/**
+ * [WHO]: LlmFn, MemoryScope, MemoryRetention, MemoryStability, FacetData, MemoryEntry, MemoryRelation, Episode, WorkEntry, EventData, StateData
+ * [FROM]: No external dependencies
+ * [TO]: Consumed by packages/mem-core/src/index.ts
+ * [HERE]: packages/mem-core/src/types.ts - foundation layer type definitions for all memory data structures
+ */
+/** Pluggable LLM function: system prompt + user message → raw text response */
+export type LlmFn = (systemPrompt: string, userMessage: string) => Promise<string>;
+export interface MemoryScope {
+    userId?: string;
+    agentId?: string;
+}
+export type MemoryRetention = "core" | "key-event" | "ambient";
+export type MemoryStability = "stable" | "situational";
+/** Structured data for Facets (Pattern/Struggle) memory types */
+export type FacetData = {
+    kind: "pattern";
+    trigger: string;
+    behavior: string;
+} | {
+    kind: "struggle";
+    problem: string;
+    attempts: string[];
+    solution: string;
+};
+export interface EventData {
+    kind: string;
+    outcome?: string;
+    emotionalWeight?: number;
+}
+export interface StateData {
+    mood: string;
+    intensity?: number;
+    horizon?: "momentary" | "short-term";
+}
+export interface MemoryRelation {
+    id: string;
+    kind: "same-project" | "tag-overlap" | "cause-of" | "caused-by" | "preference-shapes" | "repeated-pattern";
+    weight: number;
+}
+export interface MemoryEntry {
+    id: string;
+    type: "fact" | "lesson" | "preference" | "decision" | "entity" | "pattern" | "struggle" | "event";
+    /** @deprecated Use name/summary/detail instead. Kept for backward compatibility reads. */
+    content?: string;
+    /** Short title (≤30 chars) for quick identification */
+    name?: string;
+    /** One-liner cue (≤150 chars) for Memory Cue injection */
+    summary?: string;
+    /** Full content body — only injected in Active tier or via recall_memory tool */
+    detail?: string;
+    tags: string[];
+    project: string;
+    importance: number;
+    /** Adaptive memory strength (days). Grows with each successful recall — Ebbinghaus spaced repetition. */
+    strength?: number;
+    /** Ingestion time: when the system recorded this entry */
+    created: string;
+    /** Event time: when the fact actually occurred (bi-temporal, defaults to created) */
+    eventTime?: string;
+    lastAccessed?: string;
+    accessCount: number;
+    /** A-MEM style links to related memory entries */
+    relatedIds?: string[];
+    /** TTL in days — auto-evicted after expiry. undefined = permanent */
+    ttl?: number;
+    scope?: MemoryScope;
+    retention?: MemoryRetention;
+    salience?: number;
+    stability?: MemoryStability;
+    archivedAt?: string;
+    archiveReason?: string;
+    revivedAt?: string;
+    stateData?: StateData;
+    relations?: MemoryRelation[];
+    /** Structured data for pattern/struggle types (Facets) */
+    facetData?: FacetData;
+    eventData?: EventData;
+}
+export interface Episode {
+    sessionId: string;
+    project: string;
+    date: string;
+    startedAt?: string;
+    endedAt?: string;
+    timeZone?: string;
+    summary: string;
+    userGoal?: string;
+    filesModified: string[];
+    toolsUsed: Record<string, number>;
+    keyObservations: string[];
+    errors: string[];
+    tags: string[];
+    importance: number;
+    consolidated: boolean;
+    scope?: MemoryScope;
+}
+export interface WorkEntry {
+    id: string;
+    goal: string;
+    summary: string;
+    /** Full work detail — only injected in Active tier or via recall_memory tool */
+    detail?: string;
+    project: string;
+    tags: string[];
+    importance: number;
+    strength?: number;
+    created: string;
+    eventTime?: string;
+    lastAccessed?: string;
+    accessCount: number;
+    relatedIds?: string[];
+    ttl?: number;
+    archivedAt?: string;
+    archiveReason?: string;
+    revivedAt?: string;
+    scope?: MemoryScope;
+}
+export interface Meta {
+    totalSessions: number;
+    lastConsolidation?: string;
+    version: number;
+    lastMaintenanceAt?: string;
+    lastMaintenanceVersion?: number;
+    lastBackupAt?: string;
+    lastBackupVersion?: number;
+}
+/** Mem0-style update operations */
+export type UpdateAction = "add" | "update" | "delete" | "noop";
+export interface ExtractedItem {
+    type: "preference" | "fact" | "lesson" | "decision" | "retract" | "pattern" | "struggle" | "event";
+    /** @deprecated Use name/summary/detail instead. */
+    content?: string;
+    /** Short title (≤30 chars) */
+    name?: string;
+    /** One-liner summary (≤150 chars) */
+    summary?: string;
+    /** Full content body */
+    detail?: string;
+    /** Structured data for pattern/struggle types (populated by LLM extraction) */
+    facetData?: FacetData;
+    eventData?: EventData;
+    retention?: MemoryRetention;
+    salience?: number;
+    stability?: MemoryStability;
+    stateData?: StateData;
+}
+export interface ExtractedWork {
+    goal: string;
+    summary: string;
+    /** Full detail of work accomplished */
+    detail?: string;
+}
+export interface PatternInsight {
+    entry: MemoryEntry;
+    weight: number;
+    trigger: string;
+    behavior: string;
+}
+export interface StruggleInsight {
+    entry: MemoryEntry;
+    weight: number;
+    problem: string;
+    attempts: string[];
+    solution: string;
+    resolved: boolean;
+}
+export interface InsightsReport {
+    patterns: PatternInsight[];
+    struggles: StruggleInsight[];
+    topLessons: MemoryEntry[];
+    topKnowledge: MemoryEntry[];
+    preferences: MemoryEntry[];
+    stats: {
+        knowledge: number;
+        lessons: number;
+        preferences: number;
+        facets: number;
+        episodes: number;
+        work: number;
+        totalSessions: number;
+    };
+    recommendations: string[];
+    generatedAt: string;
+}
+export interface AlignmentSnapshot {
+    identityCore: MemoryEntry[];
+    keyEvents: MemoryEntry[];
+    behaviorDrivers: MemoryEntry[];
+    currentState: MemoryEntry[];
+    relationshipEdges: Array<{
+        fromId: string;
+        toId: string;
+        kind: MemoryRelation["kind"];
+        weight: number;
+    }>;
+    conflicts: Array<{
+        aId: string;
+        bId: string;
+        reason: string;
+        severity: number;
+        recommendation: "merge" | "demote" | "forget" | "mark-situational";
+        rationale: string;
+    }>;
+    generatedAt: string;
+}
+export interface FullInsightsAtAGlance {
+    working: string;
+    hindering: string;
+    quickWins: string;
+    ambitious: string;
+}
+export interface FullInsightsProjectArea {
+    name: string;
+    sessionCount: number;
+    description: string;
+}
+export interface FullInsightsChartRow {
+    label: string;
+    value: number;
+}
+export interface FullInsightsChart {
+    id: string;
+    title: string;
+    rows: FullInsightsChartRow[];
+}
+export interface FullInsightsWin {
+    title: string;
+    description: string;
+}
+export interface FullInsightsFriction {
+    title: string;
+    description: string;
+    examples?: string[];
+}
+export interface FullInsightsFeatureToTry {
+    title: string;
+    oneLiner: string;
+    whyForYou: string;
+    exampleCode?: string;
+}
+export interface FullInsightsUsagePattern {
+    title: string;
+    summary: string;
+    detail: string;
+    pastePrompt?: string;
+}
+export interface FullInsightsReport {
+    stats: {
+        knowledge: number;
+        lessons: number;
+        preferences: number;
+        facets: number;
+        episodes: number;
+        work: number;
+        totalSessions: number;
+        aggregateToolCount?: number;
+        aggregateFileCount?: number;
+    };
+    atAGlance: FullInsightsAtAGlance;
+    projectAreas: FullInsightsProjectArea[];
+    charts: FullInsightsChart[];
+    wins: FullInsightsWin[];
+    frictions: FullInsightsFriction[];
+    patterns: PatternInsight[];
+    recommendations: string[];
+    featuresToTry: FullInsightsFeatureToTry[];
+    usagePatterns: FullInsightsUsagePattern[];
+    generatedAt: string;
+    locale: string;
+}
+export interface DeveloperPersona {
+    /** Plain language description of what this person does */
+    whatTheyDo: string;
+    /** Experience level description */
+    experienceLevel: string;
+    /** Areas of strength */
+    superpowers: string[];
+    /** Frequent blockers */
+    painPoints: string[];
+    /** Work style description */
+    workStyle: string;
+    /** One-sentence summary */
+    summary: string;
+}
+export interface HumanInsight {
+    /** Insight title - grabs attention */
+    title: string;
+    /** Insight content - like chatting with a friend */
+    content: string;
+    /** Emoji icon */
+    icon: string;
+    /** Utility level */
+    utility: "high" | "medium" | "low";
+    /** Category tags */
+    tags: string[];
+}
+export interface RootCauseInsight {
+    /** Surface symptom */
+    symptom: string;
+    /** Root cause (in plain language) */
+    rootCause: string;
+    /** Evidence */
+    evidence: string[];
+    /** Suggestion */
+    suggestion: string;
+}
+export interface ComparativeInsight {
+    /** Comparison dimension */
+    dimension: string;
+    /** User's actual situation */
+    youAre: string;
+    /** How typical users are */
+    typical: string;
+    /** Conclusion */
+    verdict: string;
+}
+export interface EnhancedInsightsReport extends FullInsightsReport {
+    /** Developer persona */
+    persona?: DeveloperPersona;
+    /** Human-readable insights */
+    humanInsights: HumanInsight[];
+    /** Root cause analysis */
+    rootCauses: RootCauseInsight[];
+    /** Comparative insights */
+    comparisons: ComparativeInsight[];
+}
+/** Injection tier for progressive recall */
+export type InjectionLevel = "active" | "cue" | "dormant";

package/dist/packages/protocol/src/commands.d.ts

@@ -0,0 +1,33 @@
+/**
+ * [WHO]: Provides ExtensionCommand, ArgumentCompletionContext, CommandCompletionItem
+ * [FROM]: No dependencies — context is generic so lifecycle/host can supply their own context type
+ * [TO]: Consumed by extensions registering slash commands and by the host command registry
+ * [HERE]: packages/protocol/src/commands.ts - stable command registration contract
+ *
+ * Host note: the host may pass a richer command context to handlers, but the protocol
+ * contract stays minimal so published packages and third-party extensions do not depend
+ * on host-only session controls.
+ */
+/** Structured context supplied while completing command arguments. */
+export interface ArgumentCompletionContext {
+    commandName: string;
+    argumentText: string;
+    argumentPrefix: string;
+    tokenIndex: number;
+    previousTokens: string[];
+}
+/** A single command-completion candidate. */
+export interface CommandCompletionItem {
+    value: string;
+    label: string;
+    description?: string;
+}
+/** A slash command an extension registers via `api.registerCommand(...)`. */
+export interface ExtensionCommand<TContext = unknown> {
+    /** Help text shown in command lists. */
+    description?: string;
+    /** Optional argument-completion provider. */
+    getArgumentCompletions?: (argumentPrefix: string, context?: ArgumentCompletionContext) => CommandCompletionItem[] | null;
+    /** Command body. `args` is the raw argument string (may be empty). */
+    handler: (args: string, ctx: TContext) => void | Promise<void>;
+}

package/dist/packages/protocol/src/flags.d.ts

@@ -0,0 +1,20 @@
+/**
+ * [WHO]: Provides ExtensionFlag, ExtensionFlagOptions, ExtensionFlagValue
+ * [FROM]: No dependencies — flags are portable extension metadata
+ * [TO]: Consumed by protocol ExtensionAPI and the host extension loader/runner
+ * [HERE]: packages/protocol/src/flags.ts - stable CLI/config flag declaration contract
+ */
+/** Supported values for extension-declared flags. */
+export type ExtensionFlagValue = boolean | string;
+/** Options an extension passes to `api.registerFlag(...)`. */
+export interface ExtensionFlagOptions {
+    description?: string;
+    type: "boolean" | "string";
+    default?: ExtensionFlagValue;
+}
+/** A runtime flag an extension declares (parsed from CLI/config by the host). */
+export interface ExtensionFlag extends ExtensionFlagOptions {
+    name: string;
+    /** Absolute path of the declaring extension (filled by the host loader). */
+    extensionPath: string;
+}

package/dist/packages/protocol/src/hooks.d.ts

@@ -0,0 +1,17 @@
+/**
+ * [WHO]: Provides HookEventName and HookHandler — public lifecycle hook vocabulary
+ * [FROM]: No dependencies — context is generic so lifecycle/host can supply their own context type
+ * [TO]: Consumed by protocol ExtensionAPI and host extension event overloads
+ * [HERE]: packages/protocol/src/hooks.ts - stable hook-name contract without payload freezing
+ *
+ * Payload types intentionally stay out of protocol for now. The host keeps rich typed
+ * overloads; protocol only publishes the event-name vocabulary that external extensions
+ * may subscribe to.
+ */
+/** Lifecycle hook names an extension may subscribe to via `api.on(...)`. */
+export type HookEventName = "resources_discover" | "session_start" | "session_ready" | "session_before_switch" | "session_switch" | "session_before_fork" | "session_fork" | "session_before_compact" | "session_compact" | "session_shutdown" | "session_before_tree" | "session_tree" | "context" | "before_agent_start" | "agent_start" | "agent_result" | "agent_abort" | "agent_end" | "turn_start" | "turn_end" | "message_start" | "message_update" | "message_end" | "tool_execution_start" | "tool_execution_update" | "tool_execution_end" | "model_select" | "tool_call" | "tool_result" | "user_bash" | "input";
+/**
+ * Hook callback. The event payload is intentionally `any` this round so host-agnostic
+ * extensions compile without per-event payload types; typed payloads remain host-owned.
+ */
+export type HookHandler<TContext = unknown> = (event: any, ctx: TContext) => void | Promise<void>;

package/dist/packages/protocol/src/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * [WHO]: Barrel for catui-protocol, the stable protocol surface for extensions
+ * [FROM]: Re-exports the per-protocol modules (tools + lifecycle + commands + hooks + flags today; themes/permissions in later P3 checkpoints)
+ * [TO]: Consumed by third-party extensions, packages/mem-core, packages/soul-core, and the host (adopting these contracts)
+ * [HERE]: packages/protocol/src/index.ts - protocol public entry
+ *
+ * Scope (this round / P3): tools (S1), lifecycle (ExtensionAPI/ExtensionContext/SessionManagerContract, S3),
+ * commands, hooks, flags, then themes/permissions. Explicitly NOT here (EVOLUTION-RESERVED): agent-profile,
+ * host-adapter, tool-runtime, a2a-bridge, memory/soul providers — see evolution/PARP.md.
+ */
+export * from "./tools.js";
+export * from "./lifecycle.js";
+export * from "./commands.js";
+export * from "./hooks.js";
+export * from "./flags.js";

package/dist/packages/protocol/src/index.js

@@ -0,0 +1 @@
+export*from"./tools.js";export*from"./lifecycle.js";export*from"./commands.js";export*from"./hooks.js";export*from"./flags.js";

package/dist/packages/protocol/src/lifecycle.d.ts

@@ -0,0 +1,61 @@
+/**
+ * [WHO]: Provides ExtensionAPI, ExtensionContext, ExtensionFactory, ExtensionUi,
+ *        SessionManagerContract — the extension lifecycle protocol
+ * [FROM]: Depends on ./commands, ./flags, ./hooks, and ./tools for registration contracts
+ * [TO]: Consumed by packages/mem-core (extension adapter) and third-party extensions; the host's
+ *       richer ExtensionContext/ExtensionAPI satisfy these structurally (extensions load dynamically)
+ * [HERE]: packages/protocol/src/lifecycle.ts - the stable extension entry contract
+ *
+ * Scope note: event payloads are intentionally loose (HookHandler's event is `any`) this round;
+ * per-event typed payloads remain host-owned. This file carries only the surface that
+ * lets a host-agnostic extension (e.g. mem-core) compile against the SDK instead of the host package.
+ */
+import type { TSchema } from "@sinclair/typebox";
+import type { ExtensionCommand } from "./commands.js";
+import type { ExtensionFlagOptions, ExtensionFlagValue } from "./flags.js";
+import type { HookEventName, HookHandler } from "./hooks.js";
+import type { ToolContract } from "./tools.js";
+/** Read-only session info an extension may consult via `ctx.sessionManager`. */
+export interface SessionManagerContract {
+    /** Absolute path to the active session's JSONL file, if any. */
+    getSessionFile(): string | undefined;
+    /** Count sessions under `cwd` whose file mtime is newer than `sinceMs`. */
+    countTouchedSince(cwd: string, sinceMs: number, options?: {
+        sessionDir?: string;
+        excludeBasename?: string;
+        concurrency?: number;
+    }): Promise<number>;
+}
+/** UI affordances available to an extension (no-ops / undefined-safe when `hasUI` is false). */
+export interface ExtensionUi {
+    /** Surface a transient message to the user. */
+    notify(message: string, type?: "info" | "warning" | "error"): void;
+    /** Set (or clear with `undefined`) a keyed status line owned by this extension. */
+    setStatus(key: string, text: string | undefined): void;
+}
+/** Runtime context handed to extension hooks, commands, and tools. */
+export interface ExtensionContext {
+    /** Current working directory. */
+    cwd: string;
+    /** Whether an interactive UI is attached (false in print/RPC mode). */
+    hasUI: boolean;
+    /** Read-only session manager. */
+    sessionManager: SessionManagerContract;
+    /** User-facing UI affordances. */
+    ui: ExtensionUi;
+}
+/** The registration surface a host passes to an extension factory. */
+export interface ExtensionAPI {
+    /** Subscribe to a lifecycle hook. */
+    on(event: HookEventName, handler: HookHandler<ExtensionContext>): void;
+    /** Register a slash command. */
+    registerCommand(name: string, command: ExtensionCommand<ExtensionContext>): void;
+    /** Register a CLI/config flag declared by this extension. */
+    registerFlag(name: string, options: ExtensionFlagOptions): void;
+    /** Get the value of a registered CLI/config flag. */
+    getFlag(name: string): ExtensionFlagValue | undefined;
+    /** Register a model-facing tool. Generic so each call infers its own parameter schema. */
+    registerTool<TParams extends TSchema = TSchema, TDetails = unknown>(tool: ToolContract<TParams, TDetails>): void;
+}
+/** An extension's default export: receives the host API and wires up hooks/commands/tools. */
+export type ExtensionFactory = (api: ExtensionAPI) => void;

package/dist/packages/protocol/src/tools.d.ts

@@ -0,0 +1,77 @@
+/**
+ * [WHO]: Provides ToolRuntime, ToolPermissions, ToolRuntimeDescriptor (S1 seam) + ToolResult, ToolContract
+ * [FROM]: Depends on @sinclair/typebox (schema) and ./lifecycle (ExtensionContext, type-only)
+ * [TO]: Consumed by the host ToolDefinition (adopts the S1 fields) and by extensions registering tools
+ * [HERE]: packages/protocol/src/tools.ts - tool runtime seam (S1) + the stable tool contract
+ *
+ * S1 seam (refactor-plan §接缝预留): a tool may optionally declare its execution runtime and
+ * permission needs. Omitting both keeps today's behavior (local, host-policy). The host
+ * ToolOrchestrator stays the single dispatch point; browser/remote/mcp runtimes are NOT
+ * implemented this round — only the contract shape is reserved so adding them is additive.
+ */
+import type { Static, TSchema } from "@sinclair/typebox";
+import type { ExtensionContext } from "./lifecycle.js";
+/** Where a tool's execute() runs. Omitted ⇒ "local" (in the host process). */
+export type ToolRuntime = "local" | "mcp" | "remote" | "browser";
+/** Declarative permission requirements a tool may request; the host decides enforcement. */
+export interface ToolPermissions {
+    /** Filesystem paths the tool intends to read / write, if constrained. */
+    filesystem?: {
+        read?: string[];
+        write?: string[];
+    };
+    /** Whether the tool may spawn shell/processes. */
+    process?: boolean;
+    /** Network hosts the tool may reach, if constrained. */
+    network?: string[];
+}
+/** S1 seam: optional runtime/permission descriptors a tool definition may carry. */
+export interface ToolRuntimeDescriptor {
+    /** Execution runtime. Omitted ⇒ "local". */
+    runtime?: ToolRuntime;
+    /** Declared permissions. Omitted ⇒ unconstrained (host policy applies). */
+    permissions?: ToolPermissions;
+}
+/** A single content block a tool returns. */
+export type ToolResultContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType?: string;
+};
+/** The result of executing a tool. */
+export interface ToolResult<TDetails = unknown> {
+    /** Model-facing content blocks. */
+    content: ToolResultContent[];
+    /** Structured details for custom rendering / downstream use. */
+    details?: TDetails;
+    /** Whether this result represents an error. */
+    isError?: boolean;
+}
+/** Callback a tool may invoke to stream partial progress. */
+export type ToolUpdateCallback<TDetails = unknown> = (details: TDetails) => void;
+/**
+ * The stable tool contract an extension registers. The host's richer ToolDefinition is a
+ * superset (adds renderCall/renderResult and tighter agent-core result types); a contract
+ * authored against this interface remains valid there because extensions load dynamically.
+ */
+export interface ToolContract<TParams extends TSchema = TSchema, TDetails = unknown> extends ToolRuntimeDescriptor {
+    /** Tool name used in LLM tool calls. */
+    name: string;
+    /** Human-readable label for UI. */
+    label?: string;
+    /** Description for the model. */
+    description: string;
+    /** Parameter schema (TypeBox). */
+    parameters: TParams;
+    /** Alternative model-facing names accepted for compatibility. */
+    aliases?: string[];
+    /** Whether the tool can safely run alongside other concurrency-safe tools. */
+    isConcurrencySafe?: boolean;
+    /** Optional usage guidance injected into the system prompt. */
+    guidance?: string;
+    /** Execute the tool. Trailing parameters are optional for simple tools. */
+    execute(toolCallId: string, params: Static<TParams>, signal?: AbortSignal, onUpdate?: ToolUpdateCallback<TDetails>, ctx?: ExtensionContext): Promise<ToolResult<TDetails>>;
+}

package/dist/packages/soul-core/src/config.d.ts

@@ -0,0 +1,20 @@
+/**
+ * [WHO]: getDefaultConfig, getSoulConfig, validateSoulConfig
+ * [FROM]: Depends on node:path, node:os
+ * [TO]: Consumed by packages/soul-core/src/index.ts
+ * [HERE]: packages/soul-core/src/config.ts -
+ */
+import type { SoulConfig } from "./types.js";
+export type { SoulConfig } from "./types.js";
+/**
+ * Get default Soul configuration
+ */
+export declare function getDefaultConfig(): SoulConfig;
+/**
+ * Get Soul configuration with overrides applied
+ */
+export declare function getSoulConfig(overrides?: Partial<SoulConfig>): SoulConfig;
+/**
+ * Validate Soul configuration
+ */
+export declare function validateSoulConfig(config: SoulConfig): void;

package/dist/packages/soul-core/src/config.js

@@ -0,0 +1 @@
+var o=Object.defineProperty;var i=(t,e)=>o(t,"name",{value:e,configurable:!0});import{join as r}from"node:path";import{homedir as n}from"node:os";function s(){return{soulDir:process.env.SOUL_DIR||r(n(),".catui","soul"),evolution:{natural:10,reflection:100,feedback:1,crisis:5},personalityLimits:{maxDelta:.05,min:.1,max:.9},valueLimits:{maxDelta:.1,min:.05,max:.5},memoryRetention:{successes:500,failures:500,patterns:200,decisions:1e3}}}i(s,"getDefaultConfig");function u(t){const e=s();return t?{soulDir:t.soulDir??e.soulDir,evolution:{...e.evolution,...t.evolution},personalityLimits:{...e.personalityLimits,...t.personalityLimits},valueLimits:{...e.valueLimits,...t.valueLimits},memoryRetention:{...e.memoryRetention,...t.memoryRetention}}:e}i(u,"getSoulConfig");function y(t){if(t.evolution.natural<1)throw new Error("evolution.natural must be at least 1");if(t.evolution.reflection<t.evolution.natural)throw new Error("evolution.reflection must be >= evolution.natural");if(t.personalityLimits.maxDelta>.2)throw new Error("personalityLimits.maxDelta must be <= 0.2 (20%)");if(t.personalityLimits.min<0||t.personalityLimits.min>1)throw new Error("personalityLimits.min must be between 0 and 1");if(t.personalityLimits.max<0||t.personalityLimits.max>1)throw new Error("personalityLimits.max must be between 0 and 1");if(t.personalityLimits.min>=t.personalityLimits.max)throw new Error("personalityLimits.min must be < personalityLimits.max");if(t.memoryRetention.successes<100)throw new Error("memoryRetention.successes must be at least 100");if(t.memoryRetention.failures<100)throw new Error("memoryRetention.failures must be at least 100")}i(y,"validateSoulConfig");export{s as getDefaultConfig,u as getSoulConfig,y as validateSoulConfig};

package/dist/packages/soul-core/src/diagnostics.d.ts

@@ -0,0 +1,23 @@
+/**
+ * [WHO]: Thin shell exporting reportDiagnostic / isDevRuntime for soul-core
+ * [FROM]: Depends only on node:events
+ * [TO]: Consumed by soul-core internals (manager.ts, evolution.ts, ...) so personality-engine logs/failures route through the unified diagnostic bus
+ * [HERE]: packages/soul-core/src/diagnostics.ts - mirrors utils/diagnostics.ts; explicit dev/debug mode prints to console, and all copies bind to the same Symbol.for slot on globalThis at runtime so the diagnostics extension subscribed via utils/diagnostics.ts receives soul-core events too
+ *
+ * Keep this file structurally identical to utils/diagnostics.ts and
+ * packages/mem-core/src/diagnostics.ts. The Symbol.for(...) slot is the
+ * runtime contract that ties all copies together.
+ */
+export type DiagnosticSeverity = "debug" | "info" | "warning" | "error";
+export type DiagnosticCategory = "network" | "fallback" | "persistence" | "config" | "extension_timeout" | "schema" | "unknown";
+export interface DiagnosticEvent {
+    source: string;
+    severity: DiagnosticSeverity;
+    category: DiagnosticCategory;
+    message: string;
+    detail?: unknown;
+    fingerprint?: string;
+    context?: Record<string, unknown>;
+}
+export declare function isDevRuntime(): boolean;
+export declare function reportDiagnostic(event: DiagnosticEvent): void;

package/dist/packages/soul-core/src/diagnostics.js

@@ -0,0 +1 @@
+var u=Object.defineProperty;var s=(e,o)=>u(e,"name",{value:o,configurable:!0});import{EventEmitter as c}from"node:events";const n=Symbol.for("catui.diagnostic.bus.v1"),l=100,i="diagnostic:event";function f(){const e=globalThis;let o=e[n];return o||(o={bus:new c,queue:[]},e[n]=o),o}s(f,"getSlot");function a(){if(process.env.NODE_ENV==="production")return!1;if(process.env.NODE_ENV==="development")return!0;const e=process.env.npm_lifecycle_event;return!!(e==="dev"||e==="test"||["1","true","yes","on"].includes((process.env.CATUI_DEBUG??"").toLowerCase()))}s(a,"isDevRuntime");function g(e){if(a()){const t=`[${e.source}]`,r=e.severity==="error"?console.error:e.severity==="warning"?console.warn:console.log;e.detail!==void 0?r(`${t} ${e.message}`,e.detail):r(`${t} ${e.message}`)}const o=f();o.bus.listenerCount(i)>0?o.bus.emit(i,e):o.queue.length<l&&o.queue.push(e)}s(g,"reportDiagnostic");export{a as isDevRuntime,g as reportDiagnostic};