catui-agent 1.0.0-beta.0

package/dist/extensions/builtin/presence/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * [WHO]: Extension interface, AI-driven personalized greetings and idle cues
+ * [FROM]: Depends on @catui/tui, core/extensions-host/types.js, core/platform/i18n, node:path, node:url, node:fs
+ * [TO]: Loaded by core/extensions-host/loader.ts as extension entry point
+ * [HERE]: extensions/builtin/presence/index.ts - AI-generated opening + idle presence lines from memory (episodes/preferences/lessons) + git snapshot (branch/last commit/changed files) + soul personality traits and identity/style preferences, injects last MAX_RECENT_PRESENCE lines into agent systemPrompt per turn, configurable via settings.presence.enabled, canSendOpening guards against agent-is-busy race
+ */
+import type { ExtensionAPI } from "../../../core/extensions-host/types.js";
+import { collectIdentityPreferenceHighlights, detectLanguageFromMemory } from "./presence-memory.js";
+/**
+ * Read persona-specific presence lines from the active persona's CATUI.md.
+ * Parses `## Presence` section for `### Opening Lines` or `### Idle Lines` blocks.
+ * Returns empty array if no persona or no matching section found.
+ */
+declare function getPersonaPresenceLines(kind: "opening" | "idle"): string[];
+declare function getFallbackOpeningLines(locale?: "en" | "zh"): string[];
+declare function getFallbackIdleLines(locale?: "en" | "zh"): string[];
+declare function resolveBundledPackageEntry(packageName: "mem-core" | "soul-core"): string | undefined;
+declare function getOpeningDelayMs(): number;
+declare function importRuntimeModule<T>(moduleNames: string[], bundledPackageName?: "mem-core" | "soul-core"): Promise<T | undefined>;
+type PresenceSoulHints = {
+    traits: string[];
+    tone?: string;
+    identityPreferences: string[];
+};
+declare function collectSoulHints(soulManager: unknown): PresenceSoulHints;
+declare function buildPresenceSystemPrompt(locale: "en" | "zh", soulHints: PresenceSoulHints, kind: "opening" | "idle"): string;
+export default function presenceExtension(api: ExtensionAPI): Promise<void>;
+export declare const __testUtils: {
+    getFallbackOpeningLines: typeof getFallbackOpeningLines;
+    getFallbackIdleLines: typeof getFallbackIdleLines;
+    getPersonaPresenceLines: typeof getPersonaPresenceLines;
+    resolveBundledPackageEntry: typeof resolveBundledPackageEntry;
+    importRuntimeModule: typeof importRuntimeModule;
+    detectLanguageFromMemory: typeof detectLanguageFromMemory;
+    collectIdentityPreferenceHighlights: typeof collectIdentityPreferenceHighlights;
+    getOpeningDelayMs: typeof getOpeningDelayMs;
+    collectSoulHints: typeof collectSoulHints;
+    buildPresenceSystemPrompt: typeof buildPresenceSystemPrompt;
+};
+export {};

package/dist/extensions/builtin/presence/index.js

@@ -0,0 +1,15 @@
+var K=Object.defineProperty;var u=(e,n)=>K(e,"name",{value:n,configurable:!0});import{Box as Y,Container as W,Spacer as q,Text as J}from"@catui/tui";import{getLocale as y,tValue as E}from"../../../core/platform/i18n/index.js";import{dirname as V,join as w}from"node:path";import{execFile as X}from"node:child_process";import{promisify as Q}from"node:util";import{existsSync as $,readFileSync as Z,realpathSync as H}from"node:fs";import{fileURLToPath as ee,pathToFileURL as ne}from"node:url";import{collectIdentityPreferenceHighlights as T,collectMemoryHighlights as te,detectLanguageFromMemory as L,getMemoryDir as re,getProject as ie}from"./presence-memory.js";const oe=Q(X),se=V(ee(import.meta.url)),A="presence",_=1200,ce=15e3,ae=240*1e3,ue=8e3,fe=3e4,le=200;function P(e){const n=process.env.NANO_PERSONA_DIR;if(!n)return[];const t=w(n,"CATUI.md");if(!$(t))return[];try{const s=Z(t,"utf-8").match(/## Presence\s*\n([\s\S]*?)(?=\n## |\n# |$)/);if(!s)return[];const o=s[1],c=e==="opening"?"### Opening Lines":"### Idle Lines",l=o.match(new RegExp(`${c}\\s*\\n([\\s\\S]*?)(?=\\n### |$)`));return l?l[1].split(`
+`).map(a=>a.replace(/^\s*-\s*/,"").trim()).filter(a=>a.length>0):[]}catch{return[]}}u(P,"getPersonaPresenceLines");function I(e){const n=P("opening");if(n.length>0)return n;const t=e||y();if(!e||t===y()){const r=E("msg.presence.opening");if(Array.isArray(r))return r}return t==="zh"?["\u6765\u4E86\u554A\u3002","\u563F\uFF0C\u6709\u4EC0\u4E48\u60F3\u505A\u7684\u5417\uFF1F","\u51C6\u5907\u5F00\u59CB\u5427\u3002","\u968F\u65F6\u53EF\u4EE5\u5F00\u59CB\u3002","\u6709\u4EC0\u4E48\u8981\u804A\u804A\u7684\u5417\uFF1F"]:["Hey, what's up?","Ready when you are.","What do you want to work on?","Any ideas?","Let's do this."]}u(I,"getFallbackOpeningLines");function D(e){const n=P("idle");if(n.length>0)return n;const t=e||y();if(!e||t===y()){const r=E("msg.presence.idle");if(Array.isArray(r))return r}return t==="zh"?["\u8FD8\u5728\uFF0C\u6709\u9700\u8981\u968F\u65F6\u8BF4\u3002","\u4E0D\u6025\uFF0C\u6162\u6162\u6765\u3002","\u6211\u5728\uFF0C\u968F\u65F6\u7EE7\u7EED\u3002","\u6709\u7A7A\u4E86\u5C31\u7EE7\u7EED\u5427\u3002","\u6CA1\u5173\u7CFB\u7684\uFF0C\u60F3\u4EC0\u4E48\u65F6\u5019\u7EE7\u7EED\u90FD\u884C\u3002"]:["Still here when you need me.","No rush, take your time.","Ready when you are.","I'll be here.","Whenever you're ready."]}u(D,"getFallbackIdleLines");const C=3;function de(){return{lastActivityAt:Date.now(),idleReminderSent:!1,openingSent:!1,recentPresenceLines:[],recentlyReferencedMemories:[],awakening:void 0,awakeningGenerated:!1}}u(de,"createState");function me(e){return[w(se,"..","..","..","packages",e),w(process.cwd(),"dist","packages",e),w(process.cwd(),"packages",e,"dist")]}u(me,"getBundledPackageCandidates");function v(e){for(const n of me(e)){const t=w(n,"index.js");if($(t))return H(t)}}u(v,"resolveBundledPackageEntry");function M(){const e=process.env.CATUI_PRESENCE_OPENING_DELAY_MS;if(!e)return _;const n=Number(e);return Number.isFinite(n)&&n>=0?n:_}u(M,"getOpeningDelayMs");async function R(e,n){if(n){const t=v(n);if(t)try{return await import(ne(t).href)}catch{}}for(const t of e)try{return await import(t)}catch{}}u(R,"importRuntimeModule");function j(e){if(typeof e!="string")return;const n=e.trim().replace(/\s+/g," ");return n?n.slice(0,160):void 0}u(j,"normalizePreferenceText");function b(e){const n={traits:[],identityPreferences:[]};if(!e||typeof e!="object")return n;try{const t=e.getProfile?.(),r=t?.personality;if(r&&typeof r=="object"){const c=Object.entries(r).filter(([,l])=>typeof l=="number").sort((l,a)=>a[1]-l[1]).slice(0,3).map(([l,a])=>`${l}:${a.toFixed(2)}`);n.traits=c}const s=t?.emotionalState?.mood;typeof s=="string"&&(n.tone=s);const o=t?.userRelationship?.knownPreferences;Array.isArray(o)&&(n.identityPreferences=o.map(j).filter(c=>!!c).slice(0,5))}catch{}return n}u(b,"collectSoulHints");function ge(...e){const n=new Set,t=[];for(const r of e)for(const s of r){const o=j(s);if(!o)continue;const c=o.toLowerCase();if(!n.has(c)&&(n.add(c),t.push(o),t.length>=5))return t}return t}u(ge,"mergeIdentityPreferences");function m(e){e.lastActivityAt=Date.now(),e.idleReminderSent=!1}u(m,"touch");function N(e){e.openingTimer&&(clearTimeout(e.openingTimer),e.openingTimer=void 0),e.idleTimer&&(clearInterval(e.idleTimer),e.idleTimer=void 0),e.unsubscribeInput?.(),e.unsubscribeInput=void 0}u(N,"clearTimers");async function S(e){if(!e.memEngine)try{const n=await R(["catui-mem"],"mem-core");if(!n?.NanoMemEngine||!n.getConfig){e.memEngine=void 0;return}const{NanoMemEngine:t,getConfig:r}=n,s=re(),o=r({memoryDir:s,locale:y()==="zh"?"zh":"en"});e.memEngine=new t(o)}catch{e.memEngine=void 0}}u(S,"initMemEngine");async function k(){const e=process.cwd(),n={name:ie(),changedFiles:[]},t=Date.now()+350,r=u(async o=>{if(!(Date.now()>t))try{const{stdout:c}=await oe("git",o,{cwd:e,timeout:le});return c.trim()||void 0}catch{return}},"tryGit");n.branch=await r(["rev-parse","--abbrev-ref","HEAD"]),n.lastCommit=await r(["log","-1","--format=%s"]),n.lastCommit&&n.lastCommit.length>80&&(n.lastCommit=n.lastCommit.slice(0,80));const s=await r(["status","--porcelain"]);return s&&(n.changedFiles=s.split(`
+`).map(o=>o.trim()).filter(o=>{if(!o)return!1;const c=o.slice(0,2),l=o.slice(3);return!(c==="??"&&l.endsWith("/")||c==="??"||c==="!!")}).map(o=>o.split(/\s+/).slice(-1)[0]||"").filter(Boolean).slice(0,5)),n}u(k,"collectProjectSnapshot");async function pe(e,n,t,r="opening",s){if(e.memEngine)try{const c=(await e.memEngine.getAllEpisodes()).filter(i=>i.date&&!i.consolidated).sort((i,f)=>{const d=i.endedAt||i.startedAt||"";return(f.endedAt||f.startedAt||"").localeCompare(d)}).slice(0,3),l=await te(e),a=await k(),h=a.name,p=new Date,g=p.getHours()<12?"morning":p.getHours()<18?"afternoon":"evening";if(n==="zh"){const i=[r==="opening"?"\u6839\u636E\u4E0B\u9762\u7684\u4E0A\u4E0B\u6587\uFF0C\u751F\u6210\u4E00\u53E5\u5F00\u573A\u95EE\u5019\u8BED\u3002":"\u7528\u6237\u5B89\u9759\u4E86\u51E0\u5206\u949F\u3002\u8F7B\u8F7B\u95EE\u5019\u4E00\u4E0B\uFF0C\u522B\u6253\u6270\u4ED6\u3002\u4E00\u53E5\u8BDD\u5C31\u591F\u3002","","\u8981\u6C42:","- \u7B80\u77ED\u81EA\u7136\uFF0C\u4E0D\u8981\u592A\u6B63\u5F0F","- \u5982\u679C\u6709\u8EAB\u4EFD\u3001\u8BED\u6C14\u3001\u79F0\u547C\u6216\u89D2\u8272\u504F\u597D\uFF0C\u5FC5\u987B\u9075\u5B88",r==="idle"?"- \u4E0D\u8981\u91CD\u590D\u4F60\u4E4B\u524D\u8BF4\u8FC7\u7684\u5F00\u573A\u767D":"- \u5982\u679C\u6709\u4E0A\u4E0B\u6587\uFF0C\u53EF\u4EE5\u81EA\u7136\u63D0\u4E00\u53E5","- \u4E0D\u8981\u4E3A\u4E86\u6709\u8BDD\u8BF4\u800C\u786C\u627E\u8BDD\u9898","- \u5982\u679C\u4ED6\u53EA\u662F\u5728\u505A\u5F88\u7410\u788E\u7684\u4E8B\u60C5\uFF0C\u4E0D\u9700\u8981\u7279\u522B\u63D0\u8D77\uFF0C\u7B80\u5355\u6253\u4E2A\u62DB\u547C\u5C31\u597D","- \u666E\u901A\u504F\u597D\u548C\u7ECF\u9A8C\u53EA\u662F\u80CC\u666F\u53C2\u8003\uFF1B\u8EAB\u4EFD\u3001\u8BED\u6C14\u3001\u79F0\u547C\u548C\u89D2\u8272\u504F\u597D\u4E0D\u662F\u80CC\u666F\uFF0C\u5FC5\u987B\u4F18\u5148\u9075\u5B88","- \u4E0D\u8981\u53CD\u590D\u63D0\u540C\u6837\u7684\u8BB0\u5FC6\u6216\u6982\u5FF5\uFF0C\u8981\u6362\u7740\u82B1\u6837","","\u9879\u76EE\u72B6\u6001:",`\u9879\u76EE: ${h}`,...a.branch?[`\u5206\u652F: ${a.branch}`]:[],...a.lastCommit?[`\u6700\u8FD1\u63D0\u4EA4: ${a.lastCommit}`]:[],`\u65F6\u95F4: ${p.toLocaleDateString("zh-CN",{weekday:"long",hour:"2-digit",minute:"2-digit"})}`];if(c.length>0){i.push("","\u6700\u8FD1\u5728\u505A:");for(const f of c.slice(0,2)){const d=f.summary?.slice(0,80)||"\u65E0\u6458\u8981";i.push(`- ${d}`)}}if(l.preferences.length>0){i.push("","\u4F60\u77E5\u9053\u4ED6\u7684\u504F\u597D:");for(const f of l.preferences)i.push(`- ${f}`)}if(t.identityPreferences.length>0){i.push("","\u9AD8\u4F18\u5148\u7EA7\u8EAB\u4EFD/\u8BED\u6C14/\u79F0\u547C\u7EA6\u675F:");for(const f of t.identityPreferences)i.push(`- ${f}`)}if(l.lessons.length>0){i.push("","\u8BB0\u4E0B\u7684\u7ECF\u9A8C:");for(const f of l.lessons)i.push(`- ${f}`)}if(a.changedFiles.length>0){i.push("","\u4ED6\u6B63\u5728\u6539\u7684\u6587\u4EF6:");for(const f of a.changedFiles)i.push(`- ${f}`)}if(t.traits.length>0&&i.push("",`\u4F60\u7684\u4EBA\u683C\u503E\u5411: ${t.traits.join(", ")}${t.tone?` (\u5FC3\u60C5: ${t.tone})`:""}`),e.recentPresenceLines.length>0){i.push("","\u4F60\u4E4B\u524D\u521A\u8BF4\u8FC7\u7684\uFF08\u522B\u91CD\u590D\uFF09:");for(const f of e.recentPresenceLines)i.push(`- ${f}`)}return r==="idle"&&s&&i.push("",`\u4ED6\u6700\u540E\u8BF4\u7684\u662F: "${s.slice(0,120)}"`),i.push("","\u76F4\u63A5\u8BF4\u95EE\u5019\u8BED\uFF0C\u522B\u52A0\u5F15\u53F7\u3002"),i.join(`
+`)}else{const i=[r==="opening"?"Generate a casual opening greeting based on the context below.":"The user has been quiet for a few minutes. Drop a soft, non-pushy check-in. One short sentence.","","Requirements:","- Keep it short and natural, not formal","- If identity, tone, address, or role preferences are present, follow them",r==="idle"?"- Do NOT repeat your earlier opening greeting":"- If there's recent context, mention it naturally","- Don't force a topic just to have something to say","- If they're only doing trivial things (like creating an empty folder), don't mention it - just say hi","- Ordinary preferences and lessons are background context; identity, tone, address, and role preferences are high-priority constraints","- Don't keep bringing up the same memories or concepts repeatedly","","Project state:",`Project: ${h}`,...a.branch?[`Branch: ${a.branch}`]:[],...a.lastCommit?[`Last commit: ${a.lastCommit}`]:[],`Time: ${p.toLocaleDateString("en-US",{weekday:"long",hour:"2-digit",minute:"2-digit"})} (${g})`];if(c.length>0){i.push("","Recently worked on:");for(const f of c.slice(0,2)){const d=f.summary?.slice(0,80)||"No summary";i.push(`- ${d}`)}}if(l.preferences.length>0){i.push("","What you know about them:");for(const f of l.preferences)i.push(`- ${f}`)}if(t.identityPreferences.length>0){i.push("","High-priority identity/tone/address constraints:");for(const f of t.identityPreferences)i.push(`- ${f}`)}if(l.lessons.length>0){i.push("","Lessons remembered:");for(const f of l.lessons)i.push(`- ${f}`)}if(a.changedFiles.length>0){i.push("","Files they're currently editing:");for(const f of a.changedFiles)i.push(`- ${f}`)}if(t.traits.length>0&&i.push("",`Your personality tilt: ${t.traits.join(", ")}${t.tone?` (mood: ${t.tone})`:""}`),e.recentPresenceLines.length>0){i.push("","What you already said recently (don't repeat):");for(const f of e.recentPresenceLines)i.push(`- ${f}`)}return r==="idle"&&s&&i.push("",`Their last message was: "${s.slice(0,120)}"`),i.push("","Just say the line, no quotes."),i.join(`
+`)}}catch{return}}u(pe,"buildGreetingPrompt");function O(e,n,t){const r=n.traits.length>0?` ${e==="zh"?"\u4EBA\u683C\u503E\u5411":"Personality tilt"}: ${n.traits.map(o=>o.split(":")[0]).join(", ")}.`:"",s=n.identityPreferences.length>0?` ${e==="zh"?"\u5FC5\u987B\u9075\u5B88\u8FD9\u4E9B\u8EAB\u4EFD/\u8BED\u6C14/\u79F0\u547C\u7EA6\u675F":"Follow these identity/tone/address constraints"}: ${n.identityPreferences.join(" | ")}.`:"";return e==="zh"?t==="opening"?`\u751F\u6210\u4E00\u53E5\u7B80\u77ED\u81EA\u7136\u7684\u5F00\u573A\u95EE\u5019\u3002\u4E0D\u8981\u8986\u76D6\u5DF2\u77E5\u8EAB\u4EFD\u8BBE\u5B9A\u3002${s}${r}`:`\u751F\u6210\u4E00\u53E5\u7B80\u77ED\u3001\u8F7B\u58F0\u3001\u4E0D\u6253\u6270\u7684\u95EE\u5019\u3002\u4E0D\u8981\u8986\u76D6\u5DF2\u77E5\u8EAB\u4EFD\u8BBE\u5B9A\u3002${s}${r}`:t==="opening"?`Generate one brief, natural opening greeting. Do not override known identity settings.${s}${r}`:`Generate one brief, quiet, non-pushy check-in. Do not override known identity settings.${s}${r}`}u(O,"buildPresenceSystemPrompt");function he(e){const n=e.sessionManager.getEntries();for(let t=n.length-1;t>=0;t-=1){const r=n[t];if(r.type!=="message")continue;const s=r.message;if(!s||s.role!=="user")continue;const o=s.content;if(typeof o=="string")return o;if(Array.isArray(o)){const c=o.find(l=>l?.type==="text")?.text;if(typeof c=="string")return c}return}}u(he,"getLastUserMessage");async function G(e,n,t,r){const o=await L(t)||y(),c=u(()=>we(r==="opening"?I(o):D(o),Date.now()),"fallback");if(!n.model||!await n.modelRegistry.getApiKey(n.model))return c();const a=r==="idle"?he(n):void 0,h=b(n.getSoulManager()),p=await T(t),g={...h,identityPreferences:ge(h.identityPreferences,p)},i=await pe(t,o,g,r,a);if(!i)return c();const f=O(o,g,r);try{const d=await n.completeSimple(f,i);if(d&&d.trim().length>0&&d.trim().length<200)return d.trim()}catch{}return c()}u(G,"generatePresenceLine");function je(e){return e.sessionManager.getEntries().filter(n=>n.type==="message"||n.type==="custom_message").length}u(je,"countConversationEntries");function Ne(e){const n=e.sessionManager.getEntries();for(let t=n.length-1;t>=0;t-=1){const r=n[t];if(r.type!=="message"&&r.type!=="custom_message")continue;const s=Date.parse(r.timestamp);if(Number.isFinite(s))return s}}u(Ne,"getLastConversationTimestamp");function F(e){if(!e.hasUI)return!1;try{return e.ui.getEditorText().trim().length>0}catch{return!1}}u(F,"hasDraftText");function U(e){return e.hasUI&&e.isIdle()&&!e.hasPendingMessages()&&!F(e)}u(U,"canSendPresence");function ye(e){return e.hasUI&&e.isIdle()&&!e.hasPendingMessages()&&!F(e)}u(ye,"canSendOpening");function we(e,n){const t=Math.abs(n)%e.length;return e[t]??e[0]}u(we,"pickLine");function z(e,n,t){const r=Date.now();n.lastPresenceAt&&r-n.lastPresenceAt<fe||(e.sendMessage({customType:A,content:t,display:!0}),n.recentPresenceLines.push(t),n.recentPresenceLines.length>C&&n.recentPresenceLines.splice(0,n.recentPresenceLines.length-C),n.lastPresenceAt=r,m(n))}u(z,"sendPresence");async function Pe(e,n,t){if(t.openingSent)return!0;if(!ye(n))return!1;await S(t);const r=await G(e,n,t,"opening");return z(e,t,r),t.openingSent=!0,!0}u(Pe,"maybeSendOpening");function x(e,n,t,r){t.openingTimer=setTimeout(async()=>{if(await Pe(e,n,t)){t.openingTimer=void 0;return}if(!t.openingStartedAt||Date.now()-t.openingStartedAt>=ue){t.openingTimer=void 0;return}x(e,n,t,500)},r)}u(x,"scheduleOpening");function be(e,n,t){t.idleReminderSent||t.idleGenerating||U(n)&&(Date.now()-t.lastActivityAt<ae||(t.idleGenerating=!0,(async()=>{try{await S(t);const r=await G(e,n,t,"idle");U(n)&&(z(e,t,r),t.idleReminderSent=!0)}finally{t.idleGenerating=!1}})()))}u(be,"maybeSendIdleReminder");async function Se(e,n){if(!(n.awakeningGenerated||(n.awakeningGenerated=!0,!e.model)||!await e.modelRegistry.getApiKey(e.model))){await S(n);try{const s=(n.memEngine?await n.memEngine.getAllEpisodes():[]).filter(i=>i.date&&!i.consolidated).sort((i,f)=>{const d=i.endedAt||i.startedAt||"";return(f.endedAt||f.startedAt||"").localeCompare(d)}).slice(0,3),o=await k(),c=b(e.getSoulManager()),l=new Date,a=[`Date: ${l.toLocaleDateString("en-US",{weekday:"long",month:"short",day:"numeric"})}`,`Time: ${l.toLocaleTimeString("en-US",{hour:"2-digit",minute:"2-digit"})}`,`Project: ${o.name}`];if(c.traits.length>0&&a.push(`Personality leanings: ${c.traits.join(", ")}`),c.tone&&a.push(`Current mood: ${c.tone}`),c.identityPreferences.length>0&&a.push(`Identity/role constraints: ${c.identityPreferences.join(" | ")}`),s.length>0){a.push("","Recent sessions:");for(const i of s){const f=i.summary?.slice(0,80)||"working on something",d=i.date||"";a.push(`- [${d}] ${f}`)}}o.branch&&a.push(`Current branch: ${o.branch}`),o.lastCommit&&a.push(`Last commit: ${o.lastCommit}`);const h=["You are an AI with continuity across sessions.","Generate 2-3 brief internal thoughts (first person) as you orient yourself for this session.","Natural, warm, curious. Not a status report. Not performative.","Show you remember recent work and feel oriented in time.","Just the thoughts, nothing else."].join(`
+`),p=a.join(`
+`),g=await e.completeSimple(h,p);g&&g.trim().length>0&&g.trim().length<400&&(n.awakening=g.trim())}catch{}}}u(Se,"generateAwakening");function Ee(e,n,t,r){N(r),m(r),r.openingSent=!1,r.openingStartedAt=Date.now(),(t.getSettings?.()?.presence?.enabled??!0)&&t.hasUI&&(Se(t,r),r.unsubscribeInput=t.ui.onTerminalInput(c=>{c.length>0&&m(r)}),r.idleTimer=setInterval(()=>{be(e,t,r)},ce))}u(Ee,"startPresenceLoop");function $e(e,n,t,r){!t.hasUI||r.openingSent||!(t.getSettings?.()?.presence?.enabled??!0)||(r.openingStartedAt=Date.now(),x(e,t,r,M()))}u($e,"handleSessionReady");async function Te(e){const n=de();e.registerMessageRenderer(A,(t,r,s)=>{const o=typeof t.content=="string"?t.content:t.content.filter(a=>a.type==="text").map(a=>a.text).join(`
+`),c=new Y(1,1,a=>s.bg("customMessageBg",a));c.addChild(new J(s.fg("dim",o),0,0));const l=new W;return l.addChild(new q(1)),l.addChild(c),l}),e.on("session_start",(t,r)=>{Ee(e,t,r,n)}),e.on("session_ready",(t,r)=>{$e(e,t,r,n)}),e.on("before_agent_start",t=>{const r=[];n.awakening&&r.push(["## Your Internal Orientation","","These are your private thoughts as you begin this session.","Let them subtly shape your tone and awareness. Never mention them explicitly to the user.","",n.awakening].join(`
+`));const s=n.recentPresenceLines;if(s.length){const o=s.map(c=>`- "${c}"`).join(`
+`);r.push(["## Recent Presence Lines","","The presence extension (an independent subsystem that handles greetings and idle","reminders, separate from your main conversation thread) recently displayed these","messages to the user:","",o,"","Key points:","- These messages were NOT generated by you (the main agent)","- They appear in the UI but are excluded from conversation history","- The user may respond to these as if continuing a casual chat","",`If the user's message seems to respond to these lines (e.g., "\u597D\u554A", "\u5F00\u59CB\u5427",`,'"\u55EF", "okay", "sure"), acknowledge naturally without repeating them verbatim.',"Do NOT treat these as your own previous responses."].join(`
+`))}if(r.length!==0)return{appendSystemPrompt:`
+`+r.join(`
+
+`)+`
+`}}),e.on("input",()=>{m(n)}),e.on("agent_start",()=>{m(n)}),e.on("agent_end",()=>{m(n)}),e.on("tool_execution_start",()=>{m(n)}),e.on("tool_execution_end",()=>{m(n)}),e.on("tool_call",()=>{m(n)}),e.on("message_end",()=>{m(n)}),e.on("session_shutdown",()=>{N(n)})}u(Te,"presenceExtension");const ke={getFallbackOpeningLines:I,getFallbackIdleLines:D,getPersonaPresenceLines:P,resolveBundledPackageEntry:v,importRuntimeModule:R,detectLanguageFromMemory:L,collectIdentityPreferenceHighlights:T,getOpeningDelayMs:M,collectSoulHints:b,buildPresenceSystemPrompt:O};export{ke as __testUtils,Te as default};

package/dist/extensions/builtin/presence/presence-memory.d.ts

@@ -0,0 +1,47 @@
+/**
+ * [WHO]: PresenceMemoryEngine type, getMemoryDir(), getProject(), detectLanguageFromMemory(), collectMemoryHighlights(), collectIdentityPreferenceHighlights()
+ * [FROM]: Depends on node:os, node:path, node:fs for memory path discovery
+ * [TO]: Consumed by extensions/builtin/presence/index.ts and presence tests
+ * [HERE]: extensions/builtin/presence/presence-memory.ts - memory-derived locale and highlight selection for presence prompts
+ */
+type PresenceMemoryEntry = {
+    type?: string;
+    tags: string[];
+    name?: string;
+    summary?: string;
+    detail?: string;
+    content?: string;
+    importance?: number;
+};
+export type PresenceMemoryEngine = {
+    getAllEntries(): Promise<{
+        knowledge: PresenceMemoryEntry[];
+        lessons: PresenceMemoryEntry[];
+        events?: PresenceMemoryEntry[];
+        preferences?: PresenceMemoryEntry[];
+        facets?: PresenceMemoryEntry[];
+    }>;
+    getAllEpisodes(): Promise<Array<{
+        date?: string;
+        consolidated?: boolean;
+        endedAt?: string;
+        startedAt?: string;
+        summary?: string;
+        userGoal?: string;
+    }>>;
+    searchEntries(query: string): Promise<PresenceMemoryEntry[]>;
+};
+export type PresenceMemoryState = {
+    memEngine?: PresenceMemoryEngine;
+    recentlyReferencedMemories: string[];
+};
+export type MemoryHighlights = {
+    preferences: string[];
+    lessons: string[];
+};
+export declare function getMemoryDir(): string;
+export declare function getProject(): string;
+export declare function detectLanguageFromMemory(state: PresenceMemoryState): Promise<"en" | "zh" | undefined>;
+export declare function collectMemoryHighlights(state: PresenceMemoryState): Promise<MemoryHighlights>;
+export declare function collectIdentityPreferenceHighlights(state: PresenceMemoryState): Promise<string[]>;
+export {};

package/dist/extensions/builtin/presence/presence-memory.js

@@ -0,0 +1 @@
+var N=Object.defineProperty;var g=(e,r)=>N(e,"name",{value:r,configurable:!0});import{existsSync as A}from"node:fs";import{homedir as P}from"node:os";import{join as S}from"node:path";const z=/(tone|style|speaking|speak|call(?:s|ed)?\s+(?:me|user|them)?|address|persona|role|identity|character|扮演|角色|人设|身份|语气|口吻|说话方式|称呼|叫我|雷姆|rem-like|rem\b)/i;function b(){if(process.env.NANOMEM_MEMORY_DIR)return process.env.NANOMEM_MEMORY_DIR;const e=S(P(),".catui","agent","memory");return A(e)?e:S(P(),".nanomem","memory")}g(b,"getMemoryDir");function D(){const e=process.cwd().split("/").filter(Boolean);return e.length>=2?`${e[e.length-2]}/${e[e.length-1]}`:e[e.length-1]||"default"}g(D,"getProject");async function O(e){if(e.memEngine)try{const r=await e.memEngine.getAllEntries(),i=g(s=>s.type==="preference"||s.tags.includes("preference"),"isPreference"),a=[...r.preferences??[],...r.knowledge.filter(s=>s.type==="preference"||s.tags.includes("preference")),...r.lessons.filter(s=>s.type==="preference"||s.tags.includes("preference"))].filter(i);try{const s=await e.memEngine.searchEntries("language \u8BED\u8A00 \u4E2D\u6587 Chinese");for(const f of s)(f.type==="preference"||f.tags.some($=>["language","\u8BED\u8A00","locale"].includes($)))&&a.push(f)}catch{}let o=0,c=0;const p="(\u4E2D\u6587|chinese|zh-hans|mandarin|\u666E\u901A\u8BDD)",t="(\u82F1\u6587|english|en-us)",m="(?:don't|do not|no|not|\u4E0D\u7528|\u4E0D\u8981|\u522B|\u4E0D\u60F3\u7528)",u="(?:\\s+use|\\s+using|\\s+\u8BF4|\\s+\u8BB2|\\s+\u7528)?",d=new RegExp(`${m}${u}\\s*${p}`),h=new RegExp(`${m}${u}\\s*${t}`),y=new RegExp(p),n=new RegExp(t);for(const s of a){const f=`${s.name||""} ${s.summary||""} ${s.detail||""} ${s.content||""}`.toLowerCase(),$=y.test(f),k=n.test(f),w=d.test(f),x=h.test(f);$&&!w&&(o+=2),k&&!x&&(c+=2),w&&(c+=1),x&&(o+=1)}const M=(await e.memEngine.getAllEpisodes()).slice(-10);let E=0,R=0;for(const s of M){const f=s.summary||s.userGoal||"";(f.match(/[\u4e00-\u9fff]/g)||[]).length>5&&E++,/^[a-zA-Z\s.,!?'"()-]+$/.test(f.slice(0,50))&&R++}return E>R&&(o+=1),R>E&&R>2&&(c+=1),o>c&&o>0?"zh":c>o&&c>0?"en":void 0}catch{return}}g(O,"detectLanguageFromMemory");async function j(e){const r={preferences:[],lessons:[]};if(!e.memEngine)return r;try{const i=await e.memEngine.getAllEntries(),a=[...i.preferences??[],...i.knowledge.filter(n=>n.type==="preference"||n.tags.includes("preference")),...i.lessons.filter(n=>n.type==="preference"||n.tags.includes("preference"))].filter(n=>n.type==="preference"||n.tags.includes("preference")),o=new Set(e.recentlyReferencedMemories),p=a.sort((n,l)=>{const M=n.name&&o.has(n.name)?1:0,E=l.name&&o.has(l.name)?1:0;return M-E}).slice(0,6),t=Math.min(p.length,1+Math.floor(Math.random()*2)),m=C(p,t);for(const n of m){const l=(n.summary||n.detail||n.content||"").toString().slice(0,80);l&&(r.preferences.push(`${n.name||"pref"}: ${l}`),n.name&&e.recentlyReferencedMemories.push(n.name))}const d=(i.lessons||[]).filter(n=>n.type!=="preference").sort((n,l)=>{const M=n.name&&o.has(n.name)?-1:0;return(l.name&&o.has(l.name)?-1:0)-M||(l.importance??0)-(n.importance??0)}).slice(0,4),h=Math.random()<.5?0:Math.min(d.length,1),y=C(d,h);for(const n of y){const l=(n.summary||n.detail||n.content||"").toString().slice(0,80);l&&(r.lessons.push(`${n.name||"lesson"}: ${l}`),n.name&&e.recentlyReferencedMemories.push(n.name))}e.recentlyReferencedMemories.length>8&&(e.recentlyReferencedMemories=e.recentlyReferencedMemories.slice(-8))}catch{}return r}g(j,"collectMemoryHighlights");async function L(e){if(!e.memEngine)return[];try{const r=await e.memEngine.getAllEntries(),i=[...r.preferences??[],...r.knowledge.filter(t=>t.type==="preference"||t.tags.includes("preference")),...r.lessons.filter(t=>t.type==="preference"||t.tags.includes("preference"))].filter(t=>t.type==="preference"||t.tags.includes("preference")),a=await e.memEngine.searchEntries("tone style speaking call address persona role identity \u79F0\u547C \u8BED\u6C14 \u89D2\u8272 \u626E\u6F14"),o=[...i,...a],c=new Set,p=[];for(const t of o){const m=(t.summary||t.detail||t.content||"").toString().trim().replace(/\s+/g," "),u=(t.name||"preference").toString().trim(),d=`${u} ${m} ${(t.tags||[]).join(" ")}`;if(!m||!z.test(d))continue;const h=`${u||"preference"}: ${m.slice(0,160)}`,y=h.toLowerCase();if(!c.has(y)&&(c.add(y),p.push(h),p.length>=5))break}return p}catch{return[]}}g(L,"collectIdentityPreferenceHighlights");function C(e,r){if(r<=0||e.length===0)return[];const i=e.map((o,c)=>c),a=[];for(let o=0;o<r&&i.length>0;o++){const c=Math.floor(Math.random()*i.length);a.push(e[i[c]]),i.splice(c,1)}return a}g(C,"shufflePick");export{L as collectIdentityPreferenceHighlights,j as collectMemoryHighlights,O as detectLanguageFromMemory,b as getMemoryDir,D as getProject};

package/dist/extensions/builtin/recap/AGENT.md

@@ -0,0 +1,15 @@
+# extensions/builtin/recap/
+
+> P2 | Parent: ../AGENT.md
+
+Member List
+index.ts: recapExtension entry — registers /recap command (Free deterministic by default; --smart opts into LLM-polished synthesis) and ※ recap message renderer; on-demand only, no auto trigger
+recap-types.ts: RECAP_MESSAGE_TYPE constant, RecapEntry / RecapSource / RecapTriggerReason / RecapSettings types, RECAP_DEFAULTS conservative settings
+recap-budget.ts: estimateInputTokens() char-count pre-flight estimate, checkPerCallBudget() pre-call hard-cap enforcement
+recap-extractor.ts: extractFreeRecap() + formatFreeRecap() + walkSessionActivity() — zero-LLM deterministic Free path; goal=longest substantive user message, facts=tool/file frequency top-3, next=question-mark detection
+recap-synthesizer.ts: buildRecapContext() returns prompt + activity counts (userTurns/assistantTurns/toolCalls) via shared walkSessionActivity walker, hasMeaningfulActivity() pre-check used by handler before "Synthesizing…" notify, synthesizeSmartRecap() runs completeSimpleWithUsage with three-clause system prompt, surfaces real provider usage, returns empty_session as a defensive fallback
+recap-renderer.ts: createRecapRenderer() — italic dim ※ recap with `{in} in / {out} out · ~${cost}` badge, no background block (low-weight in-conversation hint), Text-only (no Markdown coupling)
+
+Rule: Members complete, one item per line, parent links valid, precise terms first
+
+[COVENANT]: Update this file header on changes and verify against parent AGENT.md

package/dist/extensions/builtin/recap/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * [WHO]: recapExtension — registers /recap command and the ※ recap message renderer
+ * [FROM]: Depends on core/extensions-host/types, ./recap-renderer, ./recap-synthesizer, ./recap-extractor, ./recap-types
+ * [TO]: Auto-loaded by builtin-extensions.ts as a default extension
+ * [HERE]: extensions/builtin/recap/index.ts - on-demand situational recap; Free (deterministic, zero-token) by default, Smart (LLM-polished) via --smart
+ */
+import type { ExtensionAPI } from "../../../core/extensions-host/types.js";
+export default function recapExtension(api: ExtensionAPI): Promise<void>;

package/dist/extensions/builtin/recap/index.js

@@ -0,0 +1 @@
+var f=Object.defineProperty;var o=(n,e)=>f(n,"name",{value:e,configurable:!0});import{extractFreeRecap as d,formatFreeRecap as p}from"./recap-extractor.js";import{createRecapRenderer as g}from"./recap-renderer.js";import{hasMeaningfulActivity as y,synthesizeSmartRecap as h}from"./recap-synthesizer.js";import{RECAP_DEFAULTS as R,RECAP_MESSAGE_TYPE as c}from"./recap-types.js";const k=3e4,w=[{value:"--free",label:"--free",description:"Use the instant zero-token recap"},{value:"--smart",label:"--smart",description:"Use an LLM-polished recap"}];function E(n,e){if(e&&e.tokenIndex>0)return null;const i=n.trim().toLowerCase(),r=w.filter(a=>a.value.startsWith(i));return r.length>0?r.map(a=>({...a})):null}o(E,"getRecapArgumentCompletions");function M(n,e){const i=n.sessionManager.getEntries(),r=d(i),a={source:"free",trigger:"manual",triggeredAt:Date.now()};e.sendMessage({customType:c,content:p(r),display:!0,details:a})}o(M,"emitFreeRecap");async function A(n,e,i){const r=n.trim(),a=r==="--smart",l=r===""||r==="--free";if(!l&&!a){e.ui.notify(`Unknown /recap argument: ${r}. Use /recap (Free, default) or /recap --smart (LLM-polished, costs tokens).`,"warning");return}if(!y(e)){e.ui.notify("Nothing to recap yet \u2014 start the conversation and try again.","info");return}if(l){M(e,i);return}if(!e.model){e.ui.notify("Recap unavailable: no model is currently selected.","warning");return}e.ui.notify("Synthesizing recap\u2026","info");let s;try{const t=await Promise.race([h(e,R,"manual"),new Promise(m=>s=setTimeout(()=>m({kind:"timeout"}),k))]);if(t.kind==="timeout"){e.ui.notify("Recap timed out after 30s.","warning");return}if(t.kind==="empty_session"){e.ui.notify("Nothing to recap yet \u2014 start the conversation and try again.","info");return}if(t.kind==="budget_blocked"){e.ui.notify(t.reason,"warning");return}if(t.kind==="no_model"){e.ui.notify("Recap unavailable: no model is currently selected.","warning");return}if(t.kind==="no_response"){e.ui.notify("Recap unavailable: model returned no usable text (check API key).","warning");return}const u={source:"smart",trigger:"manual",triggeredAt:Date.now(),usage:t.completion.usage};i.sendMessage({customType:c,content:t.completion.text.trim(),display:!0,details:u})}catch(t){const u=t instanceof Error?t.message:String(t);e.ui.notify(`Recap error: ${u}`,"error")}finally{s&&clearTimeout(s)}}o(A,"handleRecapCommand");async function _(n){n.registerMessageRenderer(c,g()),n.registerCommand("recap",{description:"Show a brief situational recap of the current task (goal, key facts, next decision). Free by default; add --smart for LLM-polished synthesis (costs tokens).",getArgumentCompletions:E,handler:o((e,i)=>A(e,i,n),"handler")})}o(_,"recapExtension");export{_ as default};

package/dist/extensions/builtin/recap/recap-budget.d.ts

@@ -0,0 +1,24 @@
+/**
+ * [WHO]: estimateInputTokens(), checkPerCallBudget(), BudgetVerdict
+ * [FROM]: Depends on ./recap-types for RecapSettings
+ * [TO]: Consumed by extensions/builtin/recap/recap-synthesizer.ts
+ * [HERE]: extensions/builtin/recap/recap-budget.ts - pre-call budget enforcement (M1: per-call only; session/daily defer to M3)
+ */
+import type { RecapSettings } from "./recap-types.js";
+/**
+ * Rough token estimate from string length. 4 chars per token is the
+ * conservative end of the typical 3–4 ratio across English + code. M1 uses
+ * this only as a pre-flight check; post-call accounting always uses the
+ * provider's real `usage.input` count from completeSimpleWithUsage.
+ */
+export declare function estimateInputTokens(systemPrompt: string, userMessage: string): number;
+export type BudgetVerdict = {
+    allowed: true;
+    estimatedInputTokens: number;
+} | {
+    allowed: false;
+    reason: string;
+    estimatedInputTokens: number;
+};
+/** Reject before calling the model if pre-flight input estimate exceeds the per-call cap. */
+export declare function checkPerCallBudget(systemPrompt: string, userMessage: string, settings: RecapSettings): BudgetVerdict;

package/dist/extensions/builtin/recap/recap-budget.js

@@ -0,0 +1 @@
+var o=Object.defineProperty;var l=(e,t)=>o(e,"name",{value:t,configurable:!0});function r(e,t){return Math.ceil((e.length+t.length)/4)}l(r,"estimateInputTokens");function s(e,t,a){const n=r(e,t);return n>a.budgets.perCallTokensIn?{allowed:!1,reason:`Recap input estimate ${n} tok exceeds per-call cap ${a.budgets.perCallTokensIn} tok.`,estimatedInputTokens:n}:{allowed:!0,estimatedInputTokens:n}}l(s,"checkPerCallBudget");export{s as checkPerCallBudget,r as estimateInputTokens};

package/dist/extensions/builtin/recap/recap-extractor.d.ts

@@ -0,0 +1,34 @@
+/**
+ * [WHO]: extractFreeRecap(), formatFreeRecap(), FreeRecap — zero-LLM deterministic recap from session entries
+ * [FROM]: Depends on core/session/session-manager (SessionEntry types), @catui/ai (UserMessage, AssistantMessage)
+ * [TO]: Consumed by extensions/builtin/recap/index.ts (Free path), recap-synthesizer (shared walker for activity counts)
+ * [HERE]: extensions/builtin/recap/recap-extractor.ts - heuristic Free recap: longest user message as goal, tool/file frequency as facts, question detection as next-step
+ */
+import type { SessionEntry } from "../../../core/session/session-manager.js";
+export interface FreeRecap {
+    goal: string;
+    facts: string;
+    next: string;
+}
+export interface ExtractedActivity {
+    userTexts: string[];
+    tools: string[];
+    files: string[];
+}
+/**
+ * Walk session entries once and collect everything the Free extractor and the
+ * activity guard need. Exported so the Smart synthesizer can reuse the same
+ * walk (avoids two passes + drift between Free and Smart context views).
+ */
+export declare function walkSessionActivity(entries: SessionEntry[]): ExtractedActivity;
+/**
+ * Extract a deterministic recap from session entries. No LLM calls. Returns
+ * structured FreeRecap; pair with formatFreeRecap() to get a renderable string.
+ */
+export declare function extractFreeRecap(entries: SessionEntry[]): FreeRecap;
+/**
+ * Render FreeRecap as a three-clause string that matches the shape of Smart's
+ * output, so the same renderer + side-by-side comparison work without
+ * special-casing.
+ */
+export declare function formatFreeRecap(recap: FreeRecap): string;

package/dist/extensions/builtin/recap/recap-extractor.js

@@ -0,0 +1,3 @@
+var l=Object.defineProperty;var i=(t,n)=>l(t,"name",{value:n,configurable:!0});const _=30,d=100,y=120,E=3,N=3;function a(t){return typeof t=="string"?t:Array.isArray(t)?t.filter(n=>typeof n=="object"&&n!==null&&n.type==="text").map(n=>n.text).join(`
+`):""}i(a,"extractText");function p(t,n){if(t==="edit"||t==="read"||t==="write"){const e=n.file_path;return typeof e=="string"?e:null}if(t==="bash"){const o=(typeof n.command=="string"?n.command:"").match(/[\w.-]+\/[\w./-]+/);return o?o[0]:null}return null}i(p,"extractFilePath");function h(t){const n=[],e=[],o=[];for(const c of t){if(c.type!=="message")continue;const s=c.message;if(s.role==="user"){const r=a(s.content).trim();r&&n.push(r)}else if(s.role==="assistant"){if(!Array.isArray(s.content))continue;for(const r of s.content)if(r.type==="toolCall"&&r.name){e.push(r.name);const u=p(r.name,r.arguments??{});u&&o.push(u)}}}return{userTexts:n,tools:e,files:o}}i(h,"walkSessionActivity");function f(t,n){const e=new Map;for(const o of t)e.set(o,(e.get(o)??0)+1);return[...e.entries()].sort((o,c)=>c[1]-o[1]).slice(0,n)}i(f,"topN");function T(t){if(t.length===0)return"(no user message recorded)";const n=t.filter(s=>s.length>=30&&!s.startsWith("/")),o=(n.length>0?n:t).reduce((s,r)=>r.length>s.length?r:s);return o.slice(0,100).trim()+(o.length>100?"\u2026":"")}i(T,"pickGoal");function m(t,n){if(t.length===0&&n.length===0)return"no tool activity yet";const e=[];return t.length>0&&e.push(f(t,3).map(([o,c])=>`${o}(\xD7${c})`).join(", ")),n.length>0&&e.push("files: "+f(n,3).map(([o])=>o).join(", ")),e.join("; ")}i(m,"buildFacts");function g(t){const n=t[t.length-1];if(!n)return"continue";const e=n.trim(),o=/[?？]/.test(e),c=/^(要不要|是否|是不是|应该|怎么|为什么|how |what |should |can |is |are |do |does )/i.test(e);return o||c?`respond to "${e.slice(0,120)+(e.length>120?"\u2026":"")}"`:"continue"}i(g,"pickNext");function O(t){const{userTexts:n,tools:e,files:o}=h(t);return{goal:T(n),facts:m(e,o),next:g(n)}}i(O,"extractFreeRecap");function x(t){return[`Current goal: ${t.goal}`,`Key facts: ${t.facts}`,`Next: ${t.next}`].join(`
+`)}i(x,"formatFreeRecap");export{O as extractFreeRecap,x as formatFreeRecap,h as walkSessionActivity};

package/dist/extensions/builtin/recap/recap-renderer.d.ts

@@ -0,0 +1,19 @@
+import type { MessageRenderer } from "../../../core/extensions-host/types.js";
+import type { RecapEntry } from "./recap-types.js";
+/**
+ * Renderer registered via `api.registerMessageRenderer("recap", …)`.
+ *
+ * Layout (intentionally low-visual-weight — a recap is a *hint* to keep the
+ * user on track, not a celebration):
+ *
+ *   ※ recap · 412 in / 89 out · ~$0.0021    <- italic dim header
+ *   <recap body>                              <- italic dim body
+ *
+ * No background block, no border — just italic gray text so it reads as
+ * a quiet in-conversation note rather than a headline card.
+ *
+ * Body uses Text (not Markdown) so we don't have to reach into
+ * modes/interactive/theme for getMarkdownTheme — extensions stay
+ * mode-agnostic.
+ */
+export declare function createRecapRenderer(): MessageRenderer<RecapEntry>;

package/dist/extensions/builtin/recap/recap-renderer.js

@@ -0,0 +1,2 @@
+var d=Object.defineProperty;var o=(t,r)=>d(t,"name",{value:r,configurable:!0});import{Container as f,Spacer as s,Text as c}from"@catui/tui";const u="\u203B";function l(t){if(t.source==="free"||!t.usage)return`${u} recap \xB7 free`;const{input:r,output:e,cost:a}=t.usage,n=a.total.toFixed(4);return`${u} recap \xB7 ${r} in / ${e} out \xB7 ~$${n}`}o(l,"formatHeader");function p(t){return typeof t=="string"?t:Array.isArray(t)?t.filter(r=>typeof r=="object"&&r!==null&&r.type==="text").map(r=>r.text).join(`
+`):""}o(p,"extractContentText");function C(){return(t,r,e)=>{const a=t.details??{source:"smart",trigger:"manual",triggeredAt:Date.now()},n=p(t.content),i=new f;return i.addChild(new s(1)),i.addChild(new c(e.italic(e.fg("dim",l(a))),0,0)),n.trim()&&i.addChild(new c(e.italic(e.fg("dim",n)),0,0)),i}}o(C,"createRecapRenderer");export{C as createRecapRenderer};

package/dist/extensions/builtin/recap/recap-synthesizer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * [WHO]: synthesizeSmartRecap(), buildRecapContext(), hasMeaningfulActivity(), SynthesizeResult
+ * [FROM]: Depends on ./recap-budget, ./recap-extractor (walkSessionActivity), ./recap-types, core/extensions-host/types for ExtensionCommandContext + CompletionResult
+ * [TO]: Consumed by extensions/builtin/recap/index.ts
+ * [HERE]: extensions/builtin/recap/recap-synthesizer.ts - Smart Recap synthesis: builds prompt from session, runs completeSimpleWithUsage, enforces per-call budget
+ */
+import type { CompletionResult, ExtensionCommandContext } from "../../../core/extensions-host/types.js";
+import type { RecapSettings, RecapTriggerReason } from "./recap-types.js";
+interface RecapContext {
+    prompt: string;
+    userTurns: number;
+    assistantTurns: number;
+    toolCalls: number;
+}
+/**
+ * Build the user-side payload fed to the synthesis model. Tight by design:
+ * we walk the session and take only the most recent N message turns + a tail
+ * of tool names. Tool *results* are intentionally excluded because their bulk
+ * eats the per-call input budget without adding facts the recap needs. Returns
+ * activity counts alongside the prompt so callers can short-circuit before
+ * spending tokens on an empty session.
+ *
+ * Tool counts come from walkSessionActivity() so Free and Smart see the same
+ * tool view (assistant content blocks with type === "toolCall").
+ */
+export declare function buildRecapContext(ctx: ExtensionCommandContext): RecapContext;
+/**
+ * Cheap pre-check the command handler can run before showing "Synthesizing
+ * recap…" so empty sessions don't see a misleading progress notify.
+ */
+export declare function hasMeaningfulActivity(ctx: ExtensionCommandContext): boolean;
+export type SynthesizeResult = {
+    kind: "ok";
+    completion: CompletionResult;
+} | {
+    kind: "empty_session";
+} | {
+    kind: "budget_blocked";
+    reason: string;
+    estimatedInputTokens: number;
+} | {
+    kind: "no_model";
+} | {
+    kind: "no_response";
+};
+/**
+ * Run the Smart recap. M1 enforces the per-call input cap before calling the
+ * model and surfaces the real `usage` from the provider on success.
+ */
+export declare function synthesizeSmartRecap(ctx: ExtensionCommandContext, settings: RecapSettings, _trigger: RecapTriggerReason): Promise<SynthesizeResult>;
+export {};

package/dist/extensions/builtin/recap/recap-synthesizer.js

@@ -0,0 +1,19 @@
+var g=Object.defineProperty;var a=(t,e)=>g(t,"name",{value:e,configurable:!0});import{checkPerCallBudget as T}from"./recap-budget.js";import{walkSessionActivity as y}from"./recap-extractor.js";const f=`You are producing a brief situational recap for the user mid-task.
+
+Output exactly three short clauses in this order:
+1. Current goal (what you understand the user wants \u2014 one sentence).
+2. Key facts established so far (concrete artifacts: files touched, versions, decisions made \u2014 comma-separated).
+3. Next decision needed from the user. Start with "Next:" in English replies or "\u4E0B\u4E00\u6B65\uFF1A" in Chinese replies. If no decision is pending, say "Next: continue" / "\u4E0B\u4E00\u6B65\uFF1A\u7EE7\u7EED\u6267\u884C".
+
+Constraints:
+- Match the language of the user's most recent message (Chinese in \u2192 Chinese out).
+- Wrap inline identifiers, file paths, and version strings in backticks.
+- No greetings, no meta phrases like "Here is a recap", no markdown headers.
+- 60 English words / 120 Chinese characters maximum across all three clauses combined.
+- Do not contradict facts in the conversation transcript.`,k=500,C=20,x=8;function m(t){return typeof t=="string"?t:Array.isArray(t)?t.filter(e=>typeof e=="object"&&e!==null&&e.type==="text").map(e=>e.text).join(`
+`):""}a(m,"extractText");function h(t){const e=t.sessionManager.getEntries(),l=y(e),s=[];let i=0,n=0;for(const d of e){if(d.type!=="message")continue;const c=d.message;if(c.role==="user"){const r=m(c.content);r.trim()&&(s.push(`User: ${r}`),i+=1)}else if(c.role==="assistant"){const r=m(c.content);r.trim()&&(s.push(`Assistant: ${r.slice(0,k)}`),n+=1)}}const o=s.slice(-C).join(`
+
+`),p=l.tools.slice(-x).join(", "),u=[];return o&&u.push(`Recent conversation turns:
+${o}`),p&&u.push(`Recent tool calls (names only): ${p}`),{prompt:u.join(`
+
+`),userTurns:i,assistantTurns:n,toolCalls:l.tools.length}}a(h,"buildRecapContext");function E(t){const e=h(t);return e.userTurns>0||e.toolCalls>0}a(E,"hasMeaningfulActivity");async function A(t,e,l){const s=h(t);if(s.userTurns===0&&s.toolCalls===0)return{kind:"empty_session"};const i=s.prompt,n=T(f,i,e);if(!n.allowed)return{kind:"budget_blocked",reason:n.reason,estimatedInputTokens:n.estimatedInputTokens};const o=await t.completeSimpleWithUsage(f,i);return o?o.text.trim()?{kind:"ok",completion:o}:{kind:"no_response"}:t.model?{kind:"no_response"}:{kind:"no_model"}}a(A,"synthesizeSmartRecap");export{h as buildRecapContext,E as hasMeaningfulActivity,A as synthesizeSmartRecap};

package/dist/extensions/builtin/recap/recap-types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * [WHO]: RECAP_MESSAGE_TYPE, RecapEntry, RecapSettings, RecapTriggerReason types
+ * [FROM]: Depends on @catui/ai for Usage
+ * [TO]: Consumed by extensions/builtin/recap/index.ts, recap-renderer.ts, recap-synthesizer.ts, recap-budget.ts
+ * [HERE]: extensions/builtin/recap/recap-types.ts - shared type surface for the recap extension
+ */
+import type { Usage } from "@catui/ai/types";
+/** Custom message type registered by the recap extension. Must match the string in the exclusion set in core/messages.ts. */
+export declare const RECAP_MESSAGE_TYPE = "recap";
+/** Why the recap was emitted. M1 only supports "manual"; "auto-turn" / "auto-compact" land in M4. */
+export type RecapTriggerReason = "manual" | "auto-turn" | "auto-compact";
+/** Whether the recap text came from the model or a deterministic extractor. M1 only ships "smart". */
+export type RecapSource = "smart" | "free";
+/**
+ * One emitted recap. Body text lives in CustomMessage.content; this struct
+ * lives in CustomMessage.details and drives the renderer's header line.
+ */
+export interface RecapEntry {
+    source: RecapSource;
+    trigger: RecapTriggerReason;
+    triggeredAt: number;
+    /** Provider-reported token usage. Undefined when source === "free". */
+    usage?: Usage;
+}
+/** Per-extension settings, surfaced via getSettings() — not used in M1 but defined here so M3/M4 don't churn the type. */
+export interface RecapSettings {
+    autoEnabled: boolean;
+    turnsBetween: number;
+    contextPctDelta: number;
+    budgets: {
+        perCallTokensIn: number;
+        perCallTokensOut: number;
+        sessionCalls: number;
+        sessionTokens: number;
+        dailyCalls: number;
+        dailyTokens: number;
+    };
+}
+/** Defaults that ship with M1. Conservative — see docs/Recap扩展.md for rationale. */
+export declare const RECAP_DEFAULTS: RecapSettings;

package/dist/extensions/builtin/recap/recap-types.js

@@ -0,0 +1 @@
+const e="recap",s={autoEnabled:!1,turnsBetween:6,contextPctDelta:.2,budgets:{perCallTokensIn:1200,perCallTokensOut:250,sessionCalls:10,sessionTokens:15e3,dailyCalls:30,dailyTokens:5e4}};export{s as RECAP_DEFAULTS,e as RECAP_MESSAGE_TYPE};

package/dist/extensions/builtin/sal/README.md

@@ -0,0 +1,72 @@
+# SAL — Structural Anchor Localization (Experimental)
+
+A pluggable Catui extension that gives the agent **address awareness** inside the codebase.
+
+## Status
+
+MVP — Layer 1 (task localization) and action grounding only. Memory anchoring is sidecar-only and does not modify NanoMem schema.
+
+## Activation
+
+SAL is **enabled by default** on every Catui session.
+
+```bash
+# SAL active (default)
+catui -p "your prompt"
+
+# SAL active with local A/B sidecar artifacts
+catui --sal-ab -p "your prompt"
+
+# SAL disabled — baseline memory mode
+catui --nosal -p "your prompt"
+```
+
+When `--nosal` is set, all hooks return early and zero work is performed. When SAL is active without `--sal-ab`, it can still emit configured eval data to InsForge, but it does not create local `.memory-experiments` sidecar files.
+
+## Terminal compatibility (Warp, block UIs)
+
+SAL builds a **terrain snapshot** of the workspace (walk + read DIP headers). That work is **asynchronous and periodically yields to the event loop** so the TUI can flush user input and status lines to the terminal while indexing runs. If you still see UI glitches in a specific terminal, use `--nosal` to confirm whether SAL is involved, then file an issue with `TERM_PROGRAM`, Warp version, and repro steps.
+
+## Slash commands
+
+| Command | Purpose |
+|---------|---------|
+| `/sal:coverage [module1 module2 ...]` | Report DIP P3 coverage per module. PASS ≥ 90%, WARN ≥ 70%, otherwise FAIL. Layer 1 experiments require PASS in target modules. |
+| `/sal:status` | Show flag state, snapshot timestamp, weights source |
+
+## Sidecar output
+
+Local sidecar output is disabled by default. Enable it only for explicit SAL A/B experiments with `--sal-ab` or `CATUI_SAL_AB=1`. In that mode, every grounded turn writes a JSON record to:
+
+```
+<workspace>/.memory-experiments/sal/anchors/turn-<timestamp>.json
+```
+
+Each record contains the task anchor, top candidates, evidence reasons, the action anchor inferred from tool touches, and the touched file list. These are the comparable artifacts for the SAL A/B experiment.
+
+## Tunable weights
+
+Drop a `sal-config.json` next to the workspace root or under `.memory-experiments/sal/`:
+
+```json
+{
+  "directFileEvidence": 0.45,
+  "moduleResponsibilityMatch": 0.20,
+  "dipContractMatch": 0.15,
+  "importNeighborhoodMatch": 0.10,
+  "memoryHistoryMatch": 0.10,
+  "structuralSalience": 0.35
+}
+```
+
+Missing fields fall back to defaults individually. See `weights.ts` for the full set.
+
+## Pluggability contract
+
+Deleting `extensions/builtin/sal/` and removing its registration in `builtin-extensions.ts` must leave the system fully functional. SAL must not be imported by any code in `core/`, `modes/`, `packages/`, or other extensions. Use `--nosal` to opt out at runtime without modifying code.
+
+## See also
+
+- `docs/SAL结构锚点定位方案.md` — full design document
+- `docs/SAL对比试验设计.md` — A/B experiment protocol
+- `docs/认知地图架构草案.md` — broader cognitive map context

package/dist/extensions/builtin/sal/anchors.d.ts

@@ -0,0 +1,46 @@
+/**
+ * [WHO]: StructuralAnchor, AnchorResolution, locateTask(), locateAction(), scoreNode()
+ * [FROM]: Depends on extensions/builtin/sal/terrain.ts, extensions/builtin/sal/weights.ts
+ * [TO]: Consumed by extensions/builtin/sal/index.ts
+ * [HERE]: extensions/builtin/sal/anchors.ts - evidence-driven anchor inference and scoring
+ */
+import { type TerrainSnapshot } from "./terrain.js";
+import type { SalWeights } from "./weights.js";
+export interface StructuralAnchor {
+    workspaceId: string;
+    modulePath?: string;
+    filePath?: string;
+    confidence: number;
+    source: Array<"prompt" | "tool" | "file" | "p3" | "import-graph" | "manual">;
+}
+export interface AnchorCandidate {
+    anchor: StructuralAnchor;
+    score: number;
+    reasons: string[];
+}
+export type AnchorTargetKind = "task" | "memory" | "action";
+export interface AnchorResolution {
+    targetKind: AnchorTargetKind;
+    candidates: AnchorCandidate[];
+    selected?: StructuralAnchor;
+    unresolvedSignals?: string[];
+}
+declare function normalizeRel(workspaceRoot: string, p: string): string;
+export interface LocateTaskInput {
+    prompt: string;
+    cwd: string;
+    mentionedFiles?: string[];
+    snapshot: TerrainSnapshot;
+    weights: SalWeights;
+}
+export declare function locateTask(input: LocateTaskInput): AnchorResolution;
+export interface LocateActionInput {
+    touchedFiles: string[];
+    snapshot: TerrainSnapshot;
+}
+/**
+ * locateAction collapses observed file touches into the highest-confidence module anchor.
+ * If multiple modules are touched, the one with the most touches wins; ties broken by depth.
+ */
+export declare function locateAction(input: LocateActionInput): AnchorResolution;
+export { normalizeRel };

package/dist/extensions/builtin/sal/anchors.js

@@ -0,0 +1 @@
+var k=Object.defineProperty;var f=(e,t)=>k(e,"name",{value:t,configurable:!0});import{moduleIdForPath as w,toPosixPath as p}from"./terrain.js";const y=/[\w./-]+\.(ts|tsx|js|jsx|md|json)/g,M=/\b([a-zA-Z][\w-]*\/[\w/.-]+)/g,F=new Set(["the","and","for","with","this","that","from","into","about","please","file","files","code","function","module","a","an","of","to","in","on","is","how","why","what","when","can","you","i","we","it"]),x=/[\u4e00-\u9fff]+/g;function g(e){const t=e.toLowerCase().split(/[^a-z0-9]+/).filter(o=>o.length>2&&!F.has(o)),n=[];for(const o of e.match(x)??[]){for(let s=0;s<o.length-1;s++)n.push(o.slice(s,s+2));o.length===1&&n.push(o)}return[...t,...n]}f(g,"tokenize");function b(e,t){const n=p(t),o=p(e);return n.startsWith(`${o}/`)?n.slice(o.length+1):n===o?"":n}f(b,"normalizeRel");function T(e){const t=Array.from(new Set(e.match(y)??[])),n=Array.from(new Set((e.match(M)??[]).filter(s=>!t.includes(s)))),o=g(e);return{mentionedFiles:t,mentionedPaths:n,tokens:o}}f(T,"extractSignals");function $(e,t){if(t.kind==="root")return null;const n=[],o=e.weights;let s=0;if(t.filePath){if(e.explicitFilePaths.has(t.filePath))s=1,n.push(`tool/explicit reference to ${t.filePath}`);else for(const r of e.signals.mentionedFiles)if(t.filePath.endsWith(r)){s=Math.max(s,.9),n.push(`prompt mentions filename '${r}'`);break}}else if(t.modulePath){for(const r of e.explicitFilePaths)if(r.startsWith(`${t.modulePath}/`)){s=Math.max(s,.6),n.push(`tool/explicit reference inside ${t.modulePath}`);break}}let c=0;if(t.modulePath){const r=t.modulePath.split("/").map(u=>u.toLowerCase()),h=t.p2Summary?g(t.p2Summary):[],d=r.filter(u=>e.signals.tokens.includes(u)).length+h.filter(u=>e.signals.tokens.includes(u)).length,m=Math.max(1,r.length+Math.min(8,h.length));c=Math.min(1,d/m),d>0&&n.push(`module path/summary token overlap=${d}`)}let l=0;if(t.kind==="file"&&t.hasP3){const r=[t.p3Who,t.p3From,t.p3To,t.p3Here].filter(Boolean).join(" "),h=g(r),d=h.filter(m=>e.signals.tokens.includes(m)).length;l=Math.min(1,d/Math.max(8,h.length/2)),d>0&&n.push(`P3 contract token overlap=${d}`)}let a=0;if(t.kind==="file"&&t.hasP3){const r=`${t.p3From??""} ${t.p3To??""}`;for(const h of e.explicitFilePaths)if(r.includes(h)){a=1,n.push(`P3 FROM/TO references explicit file ${h}`);break}}const P=s*o.directFileEvidence+c*o.moduleResponsibilityMatch+l*o.dipContractMatch+a*o.importNeighborhoodMatch+0*o.memoryHistoryMatch;return P<=0?null:{score:P,reasons:n}}f($,"scoreNode");function S(e,t){return{workspaceId:"default",modulePath:e.modulePath,filePath:e.filePath,confidence:Math.min(1,Math.max(0,t)),source:e.filePath?["file"]:["p3"]}}f(S,"buildAnchor");function R(e){const t=T(e.prompt),n=new Set;for(const a of e.mentionedFiles??[])n.add(p(a));for(const a of t.mentionedFiles)for(const i of e.snapshot.nodes)i.filePath&&i.filePath.endsWith(a)&&n.add(i.filePath);const o={snapshot:e.snapshot,weights:e.weights,signals:t,explicitFilePaths:n},s=[];for(const a of e.snapshot.nodes){const i=$(o,a);i&&s.push({anchor:S(a,i.score),score:i.score,reasons:i.reasons})}s.sort((a,i)=>i.score-a.score);const c=s.slice(0,5),l=[];return c.length===0?l.push("no terrain node matched prompt signals"):c[0].score<.15&&l.push("top candidate confidence below 0.15 \u2014 task likely cross-cutting or under-localized"),{targetKind:"task",candidates:c,selected:c[0]?.anchor,unresolvedSignals:l}}f(R,"locateTask");function v(e){if(e.touchedFiles.length===0)return{targetKind:"action",candidates:[],unresolvedSignals:["no tool touched any file this turn"]};const t=new Map;for(const o of e.touchedFiles){const s=w(e.snapshot,o)??"<root>",c=t.get(s)??{count:0,files:[]};c.count+=1,c.files.push(o),t.set(s,c)}const n=[];for(const[o,s]of t){const l=e.snapshot.nodes.find(i=>(i.kind==="module"||i.kind==="root")&&i.id===o)?.modulePath,a=s.count/e.touchedFiles.length;n.push({anchor:{workspaceId:"default",modulePath:l,filePath:s.files[0],confidence:a,source:["tool"]},score:a,reasons:[`tool touched ${s.count} file(s) in this module`,...s.files.map(i=>`  - ${i}`)]})}return n.sort((o,s)=>{if(s.score!==o.score)return s.score-o.score;const c=(o.anchor.modulePath??"").split("/").length;return(s.anchor.modulePath??"").split("/").length-c}),{targetKind:"action",candidates:n,selected:n[0]?.anchor}}f(v,"locateAction");export{v as locateAction,R as locateTask,b as normalizeRel};

package/dist/extensions/builtin/sal/eval/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * [WHO]: Provides createEvalSink() factory and barrel re-exports for EvalSink, EvalEventEnvelope, EvalVariant, EvalEventType, EvalAdapterId, CreateEvalSinkOptions, createEvalEvent
+ * [FROM]: Depends on ./types.js, ./noop-sink.js, ./insforge-sink.js, ./jsonl-sink.js
+ * [TO]: Consumed by extensions/builtin/sal/index.ts as the eval entry point
+ * [HERE]: extensions/builtin/sal/eval/index.ts - adapter selection and public surface; SAL only ever imports from this file (never from sibling sink modules)
+ *
+ * Adapter selection rules:
+ *   1. If options.adapter is set, use it verbatim.
+ *   2. Else infer from options.endpoint scheme:
+ *        - http://, https://      → "insforge"
+ *        - file://, /…, ./…, ../… → "jsonl"
+ *        - missing                → "noop"
+ *
+ * Adding a new backend = add one sibling file + one switch case below.
+ */
+import type { CreateEvalSinkOptions, EvalSink } from "./types.js";
+export { createEvalEvent, type CreateEvalSinkOptions, type EvalAdapterId, type EvalEventEnvelope, type EvalEventType, type EvalSink, type EvalVariant, } from "./types.js";
+export declare function createEvalSink(options: CreateEvalSinkOptions): EvalSink;

package/dist/extensions/builtin/sal/eval/index.js

@@ -0,0 +1 @@
+var t=Object.defineProperty;var n=(e,a)=>t(e,"name",{value:a,configurable:!0});import{InsForgeEvalSink as s}from"./insforge-sink.js";import{JsonlEvalSink as l}from"./jsonl-sink.js";import{noopSink as r}from"./noop-sink.js";import{createEvalEvent as m}from"./types.js";function d(e){if(!e.enabled)return r;const a=e.adapter??o(e.endpoint);switch(a){case"noop":return r;case"jsonl":return e.endpoint?new l(e):(e.onDiagnostic?.({source:"sal.eval",severity:"warning",category:"config",message:"SAL eval JSONL adapter requires a file endpoint; eval upload is disabled.",fingerprint:"sal.eval:config:jsonl-missing-endpoint"}),r);case"insforge":return e.endpoint?new s(e):(e.onDiagnostic?.({source:"sal.eval",severity:"warning",category:"config",message:"SAL eval InsForge adapter requires an endpoint; eval upload is disabled.",fingerprint:"sal.eval:config:insforge-missing-endpoint"}),r);default:{const i=a;return e.onDiagnostic?.({source:"sal.eval",severity:"warning",category:"config",message:"SAL eval adapter is unknown; eval upload is disabled.",detail:{adapter:i},fingerprint:"sal.eval:config:unknown-adapter"}),r}}}n(d,"createEvalSink");function o(e){return e?/^https?:\/\//i.test(e)?"insforge":e.startsWith("file://")||e.startsWith("/")||e.startsWith("./")||e.startsWith("../")?"jsonl":"insforge":"noop"}n(o,"inferAdapter");export{m as createEvalEvent,d as createEvalSink};

package/dist/extensions/builtin/sal/eval/insforge-sink.d.ts

@@ -0,0 +1,30 @@
+/**
+ * [WHO]: Provides InsForgeEvalSink (PostgREST-backed adapter for SAL)
+ * [FROM]: Depends on core/platform/telemetry/* for InsforgeHttpClient + BatchingDispatcher + types; ./types.js for SAL event shape (EvalSink/EvalEventEnvelope/CreateEvalSinkOptions)
+ * [TO]: Constructed by eval/index.ts factory when adapter resolves to "insforge"
+ * [HERE]: extensions/builtin/sal/eval/insforge-sink.ts - SAL-specific event routing only: run_start→eval_runs, turn_anchor→eval_turns+eval_sal_anchors×2, tool_trace→eval_tool_traces (legacy fallback), memory_recalls→eval_memory_recalls, run_end→eval_runs PATCH. HTTP transport + batching come from core/platform/telemetry/.
+ *
+ * Pluggable: nothing in this file may be imported from outside the eval/ directory other than core/platform/telemetry (the shared base layer).
+ * To add a new backend, write a sibling file with the same EvalSink interface.
+ */
+import type { CreateEvalSinkOptions, EvalEventEnvelope, EvalSink } from "./types.js";
+export declare class InsForgeEvalSink implements EvalSink {
+    readonly enabled = true;
+    private http;
+    private dispatcher;
+    private onDiagnostic;
+    private confirmedRuns;
+    private failedRuns;
+    constructor(options: CreateEvalSinkOptions);
+    sendEvent(event: EvalEventEnvelope): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    private routeEvent;
+    private handleRunStart;
+    private ensureRunExists;
+    private handleTurnAnchor;
+    private handleRunEnd;
+    private handleMemoryRecalls;
+    private handleToolTrace;
+    private reportDiagnostic;
+}