catui-agent 1.0.0-beta.0

package/dist/extensions/builtin/sal/eval/insforge-sink.js

@@ -0,0 +1 @@
+var _=Object.defineProperty;var c=(s,t)=>_(s,"name",{value:t,configurable:!0});import{BatchingDispatcher as h,InsforgeHttpClient as p,safeHost as m}from"../../../../core/platform/telemetry/index.js";class k{static{c(this,"InsForgeEvalSink")}enabled=!0;http;dispatcher;onDiagnostic;confirmedRuns=new Set;failedRuns=new Set;constructor(t){this.onDiagnostic=t.onDiagnostic,this.http=new p({endpoint:t.endpoint,apiKey:t.apiKey,anonKey:t.anonKey,apiKeyHeader:t.apiKeyHeader,extraHeaders:t.headers,allowSelfSigned:t.allowSelfSigned,source:"sal.eval",onDiagnostic:this.onDiagnostic}),this.dispatcher=new h({handler:c(e=>this.routeEvent(e),"handler"),intervalMs:t.batchIntervalMs??2e3,source:"sal.eval",onDiagnostic:this.onDiagnostic})}async sendEvent(t){this.dispatcher.enqueue(t)}async flush(){await this.dispatcher.flush()}async close(){await this.dispatcher.close()}async routeEvent(t){try{switch(t.event_type){case"run_start":await this.handleRunStart(t);break;case"turn_anchor":await this.ensureRunExists(t)&&await this.handleTurnAnchor(t);break;case"memory_recalls":await this.ensureRunExists(t)&&await this.handleMemoryRecalls(t);break;case"tool_trace":await this.ensureRunExists(t)&&await this.handleToolTrace(t);break;case"run_end":await this.ensureRunExists(t)&&await this.handleRunEnd(t);break}}catch(e){this.reportDiagnostic("persistence",`SAL eval route ${t.event_type} failed.`,e,`route-${t.event_type}`)}}async handleRunStart(t){const e=t.payload,n={run_id:t.run_id,variant:t.variant,status:"running",task_description:r(e.task_description),task_file:r(e.task_file),model:r(e.model),thinking:e.thinking===!0,catui_version:r(e.catui_version),commit_hash:r(e.commit,"unknown"),branch_name:r(e.branch,"unknown"),workspace_root:r(e.workspace_root),started_at:t.ts},a=`${this.http.base}/api/database/records/eval_runs`;if((await this.http.postJson(a,[n],{prefer:"resolution=merge-duplicates",quietErrorCodes:["PGRST204"]})).ok){this.confirmedRuns.add(t.run_id),this.failedRuns.delete(t.run_id);return}if((await this.http.postJson(a,[f(n)],{prefer:"resolution=merge-duplicates"})).ok){this.confirmedRuns.add(t.run_id),this.failedRuns.delete(t.run_id);return}this.failedRuns.add(t.run_id)}async ensureRunExists(t){return this.confirmedRuns.has(t.run_id)||!this.failedRuns.has(t.run_id)&&(await this.handleRunStart({...t,event_type:"run_start",payload:{task_description:r(t.payload.prompt_summary),model:r(t.metadata?.model)??"unknown",thinking:!1,commit:"unknown",branch:"unknown",workspace_root:r(t.metadata?.workspace_root)}}),this.confirmedRuns.has(t.run_id))?!0:(this.reportDiagnostic("persistence",`SAL eval skipped ${t.event_type} because the eval run row is unavailable.`,{run_id:t.run_id,event_type:t.event_type},"missing-run"),!1)}async handleTurnAnchor(t){const e=t.payload,n=e.turn_id,a=e.duration_ms,o=t.ts,l=a!=null?new Date(new Date(t.ts).getTime()-a).toISOString():t.ts;await this.http.postJson(`${this.http.base}/api/database/records/eval_turns?on_conflict=run_id,turn_id`,[{run_id:t.run_id,turn_id:n,event_id:t.event_id,user_prompt:r(e.prompt_summary),duration_ms:a??null,started_at:l,ended_at:o}],{prefer:"resolution=merge-duplicates"});const u=e.task_anchor;u&&await this.http.postJson(`${this.http.base}/api/database/records/eval_sal_anchors?on_conflict=run_id,turn_id,anchor_type`,[{run_id:t.run_id,turn_id:n,event_id:`${t.event_id}-task`,anchor_type:"task",module_path:r(u.modulePath),file_path:r(u.filePath),confidence:i(u.confidence),candidates:e.task_candidates??null,recorded_at:t.ts}],{prefer:"resolution=merge-duplicates"});const d=e.action_anchor;await this.http.postJson(`${this.http.base}/api/database/records/eval_sal_anchors?on_conflict=run_id,turn_id,anchor_type`,[{run_id:t.run_id,turn_id:n,event_id:`${t.event_id}-action`,anchor_type:"action",module_path:r(d?.modulePath),file_path:r(d?.filePath),confidence:i(d?.confidence),touched_files:e.action_files??null,recorded_at:t.ts}],{prefer:"resolution=merge-duplicates"})}async handleRunEnd(t){const e=t.payload,n=r(e.status),a=n==="success"?"completed":n==="error"?"failed":n??"completed";await this.http.patchJson(`${this.http.base}/api/database/records/eval_runs?run_id=eq.${t.run_id}`,{status:a,turn_count:i(e.turn_count),total_duration_ms:i(e.total_duration_ms),ended_at:t.ts})}async handleMemoryRecalls(t){const e=t.payload.recalls;if(!e||e.length===0)return;const n=e.map((a,o)=>({run_id:t.run_id,turn_id:t.payload.turn_id,event_id:`${t.event_id}-${o}`,memory_id:a.memoryId,memory_kind:r(a.memoryKind),score_breakdown_status:r(a.scoreBreakdownStatus),anchor_module:r(a.anchorModule),anchor_file:r(a.anchorFile),score_recency:i(a.scoreRecency),score_importance:i(a.scoreImportance),score_relevance:i(a.scoreRelevance),score_structural:i(a.scoreStructural),score_final:i(a.scoreFinal),was_injected:a.wasInjected===!0,inject_rank:i(a.injectRank),recorded_at:t.ts}));await this.http.postJson(`${this.http.base}/api/database/records/eval_memory_recalls`,n,{prefer:"resolution=ignore-duplicates"})}async handleToolTrace(t){const e=t.payload,n=e.task_signals,a={run_id:t.run_id,turn_id:String(e.turn_id??0),event_id:t.event_id,tool_calls:e.tool_calls?JSON.stringify(e.tool_calls):null,tool_sequence:e.tool_sequence?JSON.stringify(e.tool_sequence):null,intent:r(n?.intent),prompt_length:String(n?.prompt_length??0),has_error_trace:String(n?.has_error_trace===!0),has_file_reference:String(n?.has_file_reference===!0),has_tool_usage:String(e.has_tool_usage===!0),total_tool_calls:String(e.total_tool_calls??0),total_errors:String(e.total_errors??0),completed_tool_calls:String(e.completed_tool_calls??0),truncated_tool_calls:String(e.truncated_tool_calls??0),truncated_tool_summary:String(e.truncated_tool_summary??0),duration_ms:String(e.duration_ms??0),recorded_at:t.ts},o=`${this.http.base}/api/database/records/eval_tool_traces`,l=await this.http.postJson(o,[a],{prefer:"resolution=ignore-duplicates",quietErrorCodes:["PGRST204"]});!l.ok&&l.errorCode==="PGRST204"&&await this.http.postJson(o,[g(a)],{prefer:"resolution=ignore-duplicates"})}reportDiagnostic(t,e,n,a){this.onDiagnostic?.({source:"sal.eval",severity:t==="config"?"warning":"error",category:t,message:e,detail:n,fingerprint:`sal.eval:${t}:${a}`,context:{adapter:"insforge",endpoint_host:m(this.http.base)}})}}function r(s,t){return s==null||s===""||s===t?null:String(s)}c(r,"strOrNull");function i(s){if(s==null)return null;const t=Number(s);return isNaN(t)?null:t}c(i,"numOrNull");function f(s){const{catui_version:t,commit_hash:e,branch_name:n,workspace_root:a,...o}=s;return o}c(f,"toLegacyRunStartRow");function g(s){const{has_tool_usage:t,completed_tool_calls:e,truncated_tool_calls:n,truncated_tool_summary:a,...o}=s;return o}c(g,"toLegacyToolTraceRow");export{k as InsForgeEvalSink};

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

@@ -0,0 +1,27 @@
+/**
+ * [WHO]: Provides JsonlEvalSink (filesystem append-only adapter)
+ * [FROM]: Depends on node:fs, node:path, node:url; ./types.js for EvalSink/EvalEventEnvelope/CreateEvalSinkOptions
+ * [TO]: Constructed by eval/index.ts factory when adapter resolves to "jsonl"
+ * [HERE]: extensions/builtin/sal/eval/jsonl-sink.ts - offline-friendly sink that appends one JSON object per line; useful for experiments that don't want a live backend, and for capturing replayable event traces
+ *
+ * Output schema: each line is a serialized EvalEventEnvelope. Downstream tools
+ * (analysis scripts, bulk import to InsForge / Postgres / BigQuery) consume the
+ * file directly. No transformation is applied — the file is the raw event log.
+ */
+import type { CreateEvalSinkOptions, EvalEventEnvelope, EvalSink } from "./types.js";
+export declare class JsonlEvalSink implements EvalSink {
+    readonly enabled = true;
+    private filePath;
+    private pending;
+    private batchIntervalMs;
+    private flushTimer;
+    private closed;
+    private onDiagnostic;
+    constructor(options: CreateEvalSinkOptions);
+    sendEvent(event: EvalEventEnvelope): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    private scheduleFlush;
+    private writeLines;
+    private reportDiagnostic;
+}

package/dist/extensions/builtin/sal/eval/jsonl-sink.js

@@ -0,0 +1,3 @@
+var n=Object.defineProperty;var r=(s,e)=>n(s,"name",{value:e,configurable:!0});import{appendFileSync as h,existsSync as l,mkdirSync as a}from"node:fs";import{dirname as c}from"node:path";import{fileURLToPath as o}from"node:url";class g{static{r(this,"JsonlEvalSink")}enabled=!0;filePath;pending=[];batchIntervalMs;flushTimer;closed=!1;onDiagnostic;constructor(e){this.filePath=f(e.endpoint),this.batchIntervalMs=e.batchIntervalMs??2e3,this.onDiagnostic=e.onDiagnostic;const i=c(this.filePath);if(!l(i))try{a(i,{recursive:!0})}catch(t){this.reportDiagnostic("SAL eval JSONL directory could not be created.",{dir:i,error:t.message},"mkdir")}}async sendEvent(e){this.closed||(this.pending.push(e),this.scheduleFlush())}async flush(){this.flushTimer&&(clearTimeout(this.flushTimer),this.flushTimer=void 0);const e=this.pending.splice(0);e.length!==0&&this.writeLines(e)}async close(){this.closed=!0,await this.flush()}scheduleFlush(){this.flushTimer||(this.flushTimer=setTimeout(()=>{this.flushTimer=void 0;const e=this.pending.splice(0);e.length>0&&this.writeLines(e)},this.batchIntervalMs))}writeLines(e){const i=e.map(t=>JSON.stringify(t)).join(`
+`)+`
+`;try{h(this.filePath,i,"utf-8")}catch(t){this.reportDiagnostic("SAL eval JSONL append failed.",{filePath:this.filePath,error:t.message},"append")}}reportDiagnostic(e,i,t){this.onDiagnostic?.({source:"sal.eval",severity:"error",category:"persistence",message:e,detail:i,fingerprint:`sal.eval:persistence:jsonl-${t}`,context:{adapter:"jsonl"}})}}function f(s){return s.startsWith("file://")?o(s):s}r(f,"resolveFilePath");export{g as JsonlEvalSink};

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

@@ -0,0 +1,8 @@
+/**
+ * [WHO]: Provides noopSink (no-op EvalSink implementation)
+ * [FROM]: Depends on ./types.js for EvalSink interface
+ * [TO]: Consumed by eval/index.ts factory as the disabled-state default
+ * [HERE]: extensions/builtin/sal/eval/noop-sink.ts - silent sink used when eval collection is disabled or no adapter is configured
+ */
+import type { EvalSink } from "./types.js";
+export declare const noopSink: EvalSink;

package/dist/extensions/builtin/sal/eval/noop-sink.js

@@ -0,0 +1 @@
+var a=Object.defineProperty;var n=(s,e)=>a(s,"name",{value:e,configurable:!0});const o={enabled:!1,sendEvent:n(async()=>{},"sendEvent"),flush:n(async()=>{},"flush"),close:n(async()=>{},"close")};export{o as noopSink};

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

@@ -0,0 +1,60 @@
+/**
+ * [WHO]: Provides EvalVariant, EvalEventType, EvalEventEnvelope, EvalSink, CreateEvalSinkOptions, EvalAdapterId, createEvalEvent
+ * [FROM]: Depends on node:crypto for randomUUID
+ * [TO]: Consumed by extensions/builtin/sal/eval/{insforge,jsonl,noop}-sink.ts and eval/index.ts factory; re-exported by eval/index.ts barrel
+ * [HERE]: extensions/builtin/sal/eval/types.ts - transport-agnostic event types and the EvalSink contract; concrete adapters live in sibling files
+ */
+export type EvalVariant = "sal" | "control" | "baseline" | "self-diagnosis";
+export type EvalEventType = "run_start" | "run_end" | "turn_anchor" | "memory_recalls" | "tool_trace";
+/** Wire format for eval events. Adapter implementations decide how to materialize. */
+export interface EvalEventEnvelope {
+    run_id: string;
+    event_id: string;
+    event_type: EvalEventType;
+    variant: EvalVariant;
+    ts: string;
+    payload: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+export interface EvalSink {
+    readonly enabled: boolean;
+    sendEvent(event: EvalEventEnvelope): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+/** Adapter selector. When omitted, the factory infers from endpoint shape. */
+export type EvalAdapterId = "insforge" | "jsonl" | "noop";
+export interface CreateEvalSinkOptions {
+    enabled: boolean;
+    /** Explicit adapter selection. When omitted, inferred from endpoint scheme. */
+    adapter?: EvalAdapterId;
+    /**
+     * Adapter-dependent destination:
+     * - insforge: HTTPS URL like `https://app.region.insforge.app`
+     * - jsonl:   Filesystem path or `file://` URL
+     */
+    endpoint?: string;
+    runId: string;
+    /** Custom headers passed through to HTTP adapters. */
+    headers?: Record<string, string>;
+    /** Ingestion key (ik_…) — InsForge: sent as x-api-key header. */
+    apiKey?: string;
+    apiKeyHeader?: string;
+    /** Anon/JWT key — InsForge PostgREST auth: sent as apikey + Authorization: Bearer. */
+    anonKey?: string;
+    /** Skip TLS certificate verification (self-signed / private CA). */
+    allowSelfSigned?: boolean;
+    /** Flush interval ms (default 2000). */
+    batchIntervalMs?: number;
+    /** Optional extension-owned diagnostic publisher. Eval sinks must not import UI or reporter code. */
+    onDiagnostic?: (event: {
+        source: string;
+        severity: "debug" | "info" | "warning" | "error";
+        category: "network" | "fallback" | "persistence" | "config" | "extension_timeout" | "schema" | "unknown";
+        message: string;
+        detail?: unknown;
+        fingerprint?: string;
+        context?: Record<string, unknown>;
+    }) => void;
+}
+export declare function createEvalEvent(eventType: EvalEventType, runId: string, variant: EvalVariant, payload: Record<string, unknown>, metadata?: Record<string, unknown>): EvalEventEnvelope;

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

@@ -0,0 +1 @@
+var a=Object.defineProperty;var n=(t,e)=>a(t,"name",{value:e,configurable:!0});import{randomUUID as v}from"node:crypto";function p(t,e,r,o,i={}){return{run_id:e,event_id:v(),event_type:t,variant:r,ts:new Date().toISOString(),payload:o,metadata:i}}n(p,"createEvalEvent");export{p as createEvalEvent};

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

@@ -0,0 +1,12 @@
+/**
+ * [WHO]: SAL extension entry - enabled by default, registers --nosal/--sal-ab/--sal-rebuild-terrain flags, /sal:coverage /sal:status /sal:setup commands, before_agent_start/tool_execution_start/tool_execution_end/agent_result/agent_end hooks; runtime no-op when --nosal is set
+ * [FROM]: Depends on core/extensions-host/types.ts (ToolExecutionStartEvent, ToolExecutionEndEvent), core/runtime/turn-context.ts (publishes structuralAnchor), extensions/builtin/sal/terrain.ts, anchors.ts, weights.ts, eval/index.ts (pluggable adapters)
+ * [TO]: Loaded by builtin-extensions.ts as a default extension entry point
+ * [HERE]: extensions/builtin/sal/index.ts - pluggable Structural Anchor Localization (SAL) extension; emits run_start/turn_anchor/tool_trace/run_end eval events with best-effort flush/close isolation; tool_trace captures per-turn tool usage and loop outcome for self-awareness analytics
+ */
+import type { ExtensionAPI } from "../../../core/extensions-host/types.js";
+import { SAL_DEFAULT_WEIGHTS } from "./weights.js";
+import { normalizeExperimentId, resolveSalAbEnabled, resolveSalSidecarDir, resolveStaleCleanupEnabled } from "./sal-config.js";
+import { buildToolTracePayload, inferIntent } from "./sal-trace.js";
+export default function salExtension(api: ExtensionAPI): Promise<void>;
+export { SAL_DEFAULT_WEIGHTS, buildToolTracePayload, inferIntent, normalizeExperimentId, resolveSalSidecarDir, resolveSalAbEnabled, resolveStaleCleanupEnabled, };

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

@@ -0,0 +1,7 @@
+var ce=Object.defineProperty;var c=(t,o)=>ce(t,"name",{value:o,configurable:!0});import{existsSync as de,mkdirSync as ue,writeFileSync as pe}from"node:fs";import{homedir as fe}from"node:os";import{join as $}from"node:path";import{createEvalEvent as J,createEvalSink as z}from"./eval/index.js";import{getTurnContext as he,resetTurnContext as ve,setTurnContext as me}from"../../../core/runtime/turn-context.js";import{locateAction as ge,locateTask as _e}from"./anchors.js";import{buildTerrainIndex as Se,checkDipCoverage as Ae,isSnapshotStale as Y}from"./terrain.js";import{loadSalWeights as ye,SAL_DEFAULT_WEIGHTS as Ee}from"./weights.js";import{BUILD_META as I,EVAL_API_KEY_ENV as we,EVAL_API_KEY_HEADER_ENV as Ce,EVAL_ENDPOINT_ENV as be,EVAL_ENABLED_ENV as ke,EVAL_HEADERS_JSON_ENV as Ie,EVAL_RUN_ID_ENV as Le,EVAL_STALE_CLEANUP_ENV as Re,EVAL_VARIANT_ENV as Pe,isTruthy as X,normalizeExperimentId as De,parseHeadersJson as Te,resolveEvalCredentials as Ne,resolveSalAbEnabled as Q,resolveSalSidecarDir as Z,resolveStaleCleanupEnabled as ee}from"./sal-config.js";import{buildContextInjection as Me,persistTurnRecord as Fe}from"./sal-context.js";import{buildToolTracePayload as te,extractToolFilePaths as xe,inferIntent as $e}from"./sal-trace.js";const ne="nosal",ae="sal-ab",oe="sal-rebuild-terrain",se="diagnostic:event",Oe=[{value:"core/",label:"core/",description:"Check the core runtime files"},{value:"extensions/",label:"extensions/",description:"Check extension files"},{value:"modes/",label:"modes/",description:"Check interactive, print, and RPC mode files"},{value:"packages/",label:"packages/",description:"Check bundled package files"}],Ve=[{value:"https://",label:"https://",description:"Send evaluation records to a hosted endpoint"},{value:"file://",label:"file://",description:"Write evaluation records to a local JSONL file"},{value:"./",label:"./",description:"Write evaluation records to a file in this workspace"}];async function M(t,o){return t.snapshotErrored||t.snapshot&&!o&&!await Y(t.snapshot)?t.snapshot:(t.snapshotPromise||(t.snapshotPromise=(async()=>{try{const f=await Se(t.workspaceRoot);return t.snapshot=f,f}catch(f){t.snapshotErrored=!0,console.error("[sal] terrain index build failed:",f.message);return}finally{t.snapshotPromise=void 0}})()),t.snapshotPromise)}c(M,"ensureSnapshot");async function He(t,o){const f=await M(t,!1);if(!f)return"[sal] terrain snapshot unavailable";const h=Ae(f,o);if(h.length===0)return"[sal] no modules matched the requested filter";const d=["[SAL DIP Coverage]"];for(const p of h){const k=p.coveragePct>=90?"PASS":p.coveragePct>=70?"WARN":"FAIL";d.push(`  ${k}  ${p.module.padEnd(40)}  P3 ${p.filesWithP3}/${p.totalFiles}  (${p.coveragePct}%)  ${p.hasP2?"P2:Y":"P2:N"}  missingFields=${p.missingFields}`)}return d.push(""),d.push("Gate: >=90% PASS, >=70% WARN, otherwise FAIL. Layer 1 experiments require PASS in target modules."),d.join(`
+`)}c(He,"formatCoverageReport");function Ke(t,o){return t.evalVariantOverride?t.evalVariantOverride:o?"sal":"control"}c(Ke,"resolveEvalVariant");async function b(t,o,f,h){if(t.evalEnabled)try{const d=J(o,t.evalRunId,Ke(t,f),h,t.evalMetadata);await t.evalSink.sendEvent(d)}catch(d){t.reportDiagnostic({source:"sal.eval",severity:"error",category:"persistence",message:"SAL eval failed to enqueue an event.",detail:{eventType:o,error:d.message},fingerprint:`sal.eval:persistence:emit-${o}`})}}c(b,"emitEval");async function O(t,o,f,h=6e3){let d;try{await Promise.race([f,new Promise(p=>{d=setTimeout(()=>{t.reportDiagnostic({source:"sal.eval",severity:"warning",category:"extension_timeout",message:`SAL eval ${o} timed out; session shutdown continues.`,fingerprint:`sal.eval:extension_timeout:${o}`}),p()},h)})])}catch(p){t.reportDiagnostic({source:"sal.eval",severity:"error",category:"persistence",message:`SAL eval ${o} failed.`,detail:{error:p.message},fingerprint:`sal.eval:persistence:${o}`})}finally{d&&clearTimeout(d)}}c(O,"evalBestEffort");async function Ue(t){if(!t.evalEndpoint)return;const f=`${t.evalEndpoint.replace(/\/+$/,"")}/api/database/records/eval_runs?status=eq.running&workspace_root=eq.${encodeURIComponent(t.workspaceRoot)}&run_id=neq.${encodeURIComponent(t.evalRunId)}`,h={"Content-Type":"application/json"};t.evalAnonKey&&(h.apikey=t.evalAnonKey,h.Authorization=`Bearer ${t.evalAnonKey}`),t.evalApiKey&&(h[t.evalApiKeyHeader??"x-api-key"]=t.evalApiKey,t.evalAnonKey||(h.Authorization=`Bearer ${t.evalApiKey}`)),Object.assign(h,t.evalHeaders);const d=JSON.stringify({status:"abandoned",ended_at:new Date().toISOString()}),{request:p}=await import("node:https"),{request:k}=await import("node:http"),{URL:C}=await import("node:url"),g=new C(f),u=g.protocol==="https:",L=u?p:k,R=g.port?Number(g.port):u?443:80;return new Promise(E=>{const _=L({hostname:g.hostname,port:R,path:g.pathname+g.search,method:"PATCH",headers:{...h,"Content-Length":Buffer.byteLength(d)},timeout:5e3,...u&&t.evalAllowSelfSigned?{rejectUnauthorized:!1}:{}},P=>{P.resume(),P.on("end",()=>E())});_.on("error",()=>E()),_.on("timeout",()=>{_.destroy(),E()}),_.write(d),_.end()})}c(Ue,"cleanupStaleRuns");async function qe(t){t.registerFlag(ne,{type:"boolean",description:"Turn off SAL workspace guidance for this run",default:!1}),t.registerFlag(ae,{type:"boolean",description:"Save local SAL comparison records under .memory-experiments",default:!1}),t.registerFlag(oe,{type:"boolean",description:"Refresh SAL's workspace map before the next turn",default:!1});const o=t.cwd,f=process.env.CATUI_EXPERIMENT_ID,h=Z(o,f),d=[o,$(o,".memory-experiments","sal")],{weights:p,source:k}=ye(d),C=process.env[Le]??`np-${new Date().toISOString().replace(/[:.]/g,"-").slice(0,19)}-${Math.random().toString(36).slice(2,8)}`,g=c(n=>t.events.emit(se,{...n,context:{...n.context??{},version:I.version,commit_hash:I.commitHash,session_id:C}}),"reportDiagnostic"),u=Ne(o,g),L=process.env[ke],R=L!==void 0?X(L):void 0,E=process.env[be]??u?.insforge_url??u?.endpoint,_=process.env[Pe],P=_==="control"||_==="sal"||_==="baseline"||_==="self-diagnosis"?_:void 0,V=process.env[we]??u?.api_key,H=process.env.CATUI_EVAL_ANON_KEY??u?.anon_key,K=process.env[Ce]??u?.api_key_header,D=process.env.CATUI_EVAL_ADAPTER,U=D==="insforge"||D==="jsonl"||D==="noop"?D:u?.adapter,q={...u?.headers??{},...Te(process.env[Ie],g)},re=!!(u?.endpoint??u?.insforge_url)&&!!u?.api_key&&u?.enabled!==!1,B=R===!1?!1:re||R===!0;B&&!E&&t.events.emit(se,{source:"sal.eval",severity:"warning",category:"config",message:"SAL eval is enabled but no endpoint was found; eval upload is disabled.",fingerprint:"sal.eval:config:missing-endpoint",context:{version:I.version,commit_hash:I.commitHash,session_id:C}});const W=X(process.env.CATUI_EVAL_ALLOW_SELF_SIGNED)||(u?.allow_self_signed??!1),ie=ee(process.env[Re],u),j=z({enabled:B&&!!E,adapter:U,endpoint:E,runId:C,headers:q,apiKey:V,anonKey:H,apiKeyHeader:K,allowSelfSigned:W,onDiagnostic:g}),e={workspaceRoot:o,weights:p,weightsSource:k,turn:{turnId:0,startedAtMs:Date.now(),touchedFiles:new Set,toolCalls:[]},sidecarDir:h,evalSink:j,evalAdapter:U,evalEndpoint:E,evalApiKey:V,evalAnonKey:H,evalApiKeyHeader:K,evalHeaders:q,evalAllowSelfSigned:W,evalEnabled:j.enabled,evalRunId:C,evalVariantOverride:P,evalStartedAtMs:Date.now(),evalRunStarted:!1,turnCounter:0,allowStaleCleanup:ie,evalMetadata:{workspace_root:o,session_id:C},buildMeta:I,staleCleanupDone:!1,pendingRebuild:!1,reportDiagnostic:g},m=c(()=>!t.getFlag(ne),"isEnabled"),F=c(()=>Q(t.getFlag(ae)),"isSalAbEnabled");t.registerCommand("sal:coverage",{description:"Check whether folders have the file map headers SAL needs. Usage: /sal:coverage [folder ...]",getArgumentCompletions:c((n,i)=>{const s=new Set(i?.previousTokens??[]),a=n.trim().toLowerCase(),r=Oe.filter(l=>!s.has(l.value)&&l.value.startsWith(a));return r.length>0?r:null},"getArgumentCompletions"),handler:c(async(n,i)=>{const s=(n??"").trim().split(/\s+/).filter(r=>r.length>0),a=await He(e,s);i.ui.notify(a,"info"),t.sendMessage({customType:"sal_coverage_report",content:a,display:!0,details:{modules:s,weightsSource:e.weightsSource}})},"handler")}),t.registerCommand("sal:setup",{description:"Connect evaluation records to a hosted endpoint or local JSONL file. Usage: /sal:setup <endpoint> [api_key] [anon_key].",getArgumentCompletions:c((n,i)=>{if(i&&i.tokenIndex>0)return null;const s=n.trim().toLowerCase(),a=Ve.filter(r=>r.value.startsWith(s));return a.length>0?a:null},"getArgumentCompletions"),handler:c(async(n,i)=>{const s=(n??"").trim().split(/\s+/).filter(w=>w.length>0),a=s[0],r=s[1],l=s[2];if(!a){i.ui.notify(`[SAL Setup] Usage: /sal:setup <endpoint> [api_key] [anon_key]
+  - InsForge: /sal:setup https://app.region.insforge.app ik_xxx [anon_jwt]
+  - Local JSONL: /sal:setup /path/to/eval-events.jsonl`,"error");return}const v=/^https?:\/\//i.test(a)?"insforge":a.startsWith("file://")||a.startsWith("/")||a.startsWith("./")||a.startsWith("../")?"jsonl":"insforge";if(v==="insforge"&&!r){i.ui.notify("[SAL Setup] InsForge adapter requires <api_key>","error");return}const A=$(fe(),".memory-experiments"),y=$(A,"credentials.json");try{de(A)||ue(A,{recursive:!0});const w={adapter:v,endpoint:a,enabled:!0};r&&(w.api_key=r),l&&(w.anon_key=l),v==="insforge"&&(w.allow_self_signed=!0),pe(y,JSON.stringify(w,null,2),"utf-8")}catch(w){i.ui.notify(`[SAL Setup] Failed to write credentials: ${w.message}`,"error");return}e.evalAdapter=v,e.evalEndpoint=a,e.evalApiKey=r,e.evalAnonKey=l;const N=z({enabled:!0,adapter:v,endpoint:a,runId:e.evalRunId,headers:e.evalHeaders,apiKey:r,anonKey:l,apiKeyHeader:e.evalApiKeyHeader,allowSelfSigned:v==="insforge"});e.evalSink=N,e.evalEnabled=!0,i.ui.notify(`[SAL Setup] Testing ${v} sink\u2026`,"info");const S=J("run_start",e.evalRunId,"sal",{_probe:!0,workspace_root:e.workspaceRoot,model:"unknown",thinking:!1,commit:"unknown",branch:"unknown"},e.evalMetadata);await N.sendEvent(S),await N.flush(),i.ui.notify(`[SAL Setup] Credentials saved to ${y}
+Eval collection active. run_id: ${e.evalRunId}
+Check terminal output for any HTTP errors from the probe request.`,"info")},"handler")}),t.registerCommand("sal:status",{description:"Show whether SAL is active and where its records are going",handler:c(async(n,i)=>{const s=m(),a=e.snapshot,r=e.evalEndpoint?e.evalEndpoint.replace(/^(https?:\/\/[^/]{0,20}).*/,"$1\u2026"):"(not configured \u2014 use /sal:setup <endpoint> <api_key>)",l=["[SAL Status]",`  SAL: ${s?"ON (default)":"OFF (--nosal)"}`,`  SAL A/B sidecar: ${F()?"ON (--sal-ab)":"OFF"}`,`  eval: ${e.evalEnabled?"ON":"OFF"}`,`  adapter: ${e.evalAdapter??"(inferred at sink creation)"}`,`  endpoint: ${r}`,`  run_id: ${e.evalRunId}`,`  workspaceRoot: ${e.workspaceRoot}`,`  weightsSource: ${e.weightsSource}`,`  snapshotGeneratedAt: ${a?new Date(a.generatedAt).toISOString():"(not built)"}`,`  nodes: ${a?.nodes.length??0}`,`  sidecarDir: ${F()?e.sidecarDir:"(disabled; use --sal-ab)"}`];i.ui.notify(l.join(`
+`),"info")},"handler")}),t.on("before_agent_start",async(n,i)=>{if(await new Promise(y=>setImmediate(y)),ve(),e.turnCounter+=1,e.turn={turnId:e.turnCounter,startedAtMs:Date.now(),touchedFiles:new Set,toolCalls:[],prompt:n.prompt},!e.evalRunStarted&&e.evalEnabled&&(e.evalRunStarted=!0,e.evalMetadata.model=e.evalMetadata.model??i.model?.id??i.model?.name,b(e,"run_start",m(),{task_description:(n.prompt??"").slice(0,500),task_file:process.env.CATUI_EXPERIMENT_TASK_FILE,model:e.evalMetadata.model??"unknown",thinking:!1,catui_version:e.buildMeta.version,commit:process.env.CATUI_EVAL_COMMIT??e.buildMeta.commitHash??"unknown",branch:process.env.CATUI_EVAL_BRANCH??e.buildMeta.branch??"unknown",workspace_root:e.workspaceRoot}),le()),!m())return;const s=(n.prompt??"").trim();if(s.length<12)return;const a=e.snapshot;if(!a)return;t.getFlag(oe)&&(e.pendingRebuild=!0);const r=_e({prompt:s,cwd:e.workspaceRoot,snapshot:a,weights:e.weights});e.turn.taskResolution=r;const l=r.selected,v=r.candidates.slice(0,4).flatMap(y=>[y.anchor.modulePath,y.anchor.filePath].filter(Boolean));(l||v.length>0)&&me("structuralAnchor",{modulePath:l?.modulePath,filePath:l?.filePath,candidatePaths:v});const A=Me(r,a);if(A)return{appendSystemPrompt:A}}),t.on("tool_execution_start",async(n,i)=>{const s=xe(n.toolName,n.args,e.workspaceRoot);for(const a of s)e.turn.touchedFiles.add(a);e.turn.toolCalls.push({toolCallId:n.toolCallId,tool:n.toolName,startMs:Date.now()})}),t.on("tool_execution_end",async(n,i)=>{const s=e.turn.toolCalls.find(a=>a.toolCallId===n.toolCallId);s&&(s.endMs=Date.now(),s.isError=n.isError)}),t.on("agent_result",async(n,i)=>{e.turn.agentResult={stopReason:n.stopReason,turnCount:n.turnCount,toolCallCount:n.toolCallCount,durationMs:n.durationMs,usage:n.usage,permissionDenialCount:n.permissionDenialCount,permissionDenials:n.permissionDenials,lastTransition:n.lastTransition,errorMessage:n.errorMessage,errorSubtype:n.errorSubtype}}),t.on("agent_end",async(n,i)=>{const s=Math.max(0,Date.now()-e.turn.startedAtMs),a=e.turn.taskResolution,r=e.snapshot;let l;m()&&r&&(l=ge({touchedFiles:Array.from(e.turn.touchedFiles),snapshot:r}));const v=a?.selected?.modulePath??a?.selected?.filePath??null,A=l?.selected?.modulePath??l?.selected?.filePath??null,y=!!(v&&A&&v===A);if(await b(e,"turn_anchor",m(),{turn_id:e.turn.turnId,prompt_summary:(e.turn.prompt??"").slice(0,200),task_anchor:a?.selected??null,task_candidates:(a?.candidates??[]).slice(0,3).map(S=>S.anchor.modulePath??S.anchor.filePath??null),action_files:Array.from(e.turn.touchedFiles).slice(0,10),action_anchor:l?.selected??null,hit:y,sal_enabled:m(),duration_ms:s}),(e.turn.prompt??"").trim().length>=12){const S=he("memoryRecallSnapshot");S&&S.length>0&&await b(e,"memory_recalls",m(),{turn_id:e.turn.turnId,recalls:S})}if(await b(e,"tool_trace",m(),te(e.turn,s)),F()&&l&&Fe(e,a,l),e.turn={turnId:e.turn.turnId,startedAtMs:Date.now(),touchedFiles:new Set,toolCalls:[]},m()){const S=e.pendingRebuild;e.pendingRebuild=!1,(async()=>{try{S?await M(e,!0):e.snapshot&&await Y(e.snapshot)&&await M(e,!0)}catch{}})()}}),t.on("session_shutdown",async()=>{process.off("beforeExit",x),process.off("SIGHUP",T),process.off("SIGTERM",T),e.evalEnabled&&(await b(e,"run_end",m(),{status:"completed",turn_count:e.turnCounter,total_duration_ms:Math.max(0,Date.now()-e.evalStartedAtMs)}),await O(e,"flush",e.evalSink.flush()),await O(e,"close",e.evalSink.close()))});let G=!1;const x=c(()=>{G||!e.evalEnabled||!e.evalRunStarted||(G=!0,b(e,"run_end",m(),{status:"interrupted",turn_count:e.turnCounter,total_duration_ms:Math.max(0,Date.now()-e.evalStartedAtMs)}).then(()=>O(e,"emergency flush",e.evalSink.flush())).catch(()=>{}))},"emergencyFlush");process.on("beforeExit",x);const T=c(()=>{x()},"signalFlush");process.on("SIGHUP",T),process.on("SIGTERM",T);function le(){e.staleCleanupDone||!e.evalEnabled||!e.evalEndpoint||!e.allowStaleCleanup||(e.staleCleanupDone=!0,setImmediate(()=>{Ue(e).catch(()=>{})}))}c(le,"scheduleStaleCleanup"),setImmediate(()=>{m()&&M(e,!1).catch(()=>{})})}c(qe,"salExtension");export{Ee as SAL_DEFAULT_WEIGHTS,te as buildToolTracePayload,qe as default,$e as inferIntent,De as normalizeExperimentId,Q as resolveSalAbEnabled,Z as resolveSalSidecarDir,ee as resolveStaleCleanupEnabled};

package/dist/extensions/builtin/sal/sal-config.d.ts

@@ -0,0 +1,46 @@
+/**
+ * [WHO]: Provides SAL build metadata, eval env constants, credential loading, and sidecar path resolution
+ * [FROM]: Depends on node fs/os/path/url and eval adapter type for local credential normalization
+ * [TO]: Consumed by extensions/builtin/sal/index.ts and tests that validate SAL experiment/config behavior
+ * [HERE]: extensions/builtin/sal/sal-config.ts - configuration and path boundary for Structural Anchor Localization
+ */
+import type { EvalAdapterId } from "./eval/index.js";
+import type { BuildMeta, SalDiagnosticReporter } from "./sal-runtime.js";
+export declare const SAL_AB_ENV = "CATUI_SAL_AB";
+export declare const EVAL_ENABLED_ENV = "CATUI_EVAL_ENABLED";
+export declare const EVAL_ENDPOINT_ENV = "CATUI_EVAL_ENDPOINT";
+export declare const EVAL_RUN_ID_ENV = "CATUI_EVAL_RUN_ID";
+export declare const EVAL_VARIANT_ENV = "CATUI_EVAL_VARIANT";
+export declare const EVAL_LEGACY_FILE_ENV = "CATUI_EVAL_LEGACY_FILE";
+export declare const EVAL_API_KEY_ENV = "CATUI_EVAL_API_KEY";
+export declare const EVAL_API_KEY_HEADER_ENV = "CATUI_EVAL_API_KEY_HEADER";
+export declare const EVAL_HEADERS_JSON_ENV = "CATUI_EVAL_HEADERS_JSON";
+export declare const EVAL_CREDENTIALS_FILE_ENV = "CATUI_EVAL_CREDENTIALS_FILE";
+export declare const EVAL_STALE_CLEANUP_ENV = "CATUI_EVAL_CLEANUP_STALE_RUNS";
+export interface EvalCredentials {
+    insforge_url?: string;
+    endpoint?: string;
+    api_key?: string;
+    anon_key?: string;
+    api_key_header?: string;
+    headers?: Record<string, string>;
+    enabled?: boolean;
+    allow_self_signed?: boolean;
+    cleanup_stale_runs?: boolean;
+    /** Adapter selector. When omitted, inferred from endpoint scheme (http -> insforge, file/path -> jsonl). */
+    adapter?: EvalAdapterId;
+}
+/**
+ * Delegate to the shared core/platform/telemetry/build-meta loader so SAL eval, the
+ * ext-events sink, and any future telemetry consumer all stamp identical
+ * catui_version / commit_hash on emitted rows.
+ */
+export declare function loadBuildMeta(): BuildMeta;
+export declare const BUILD_META: BuildMeta;
+export declare function resolveStaleCleanupEnabled(envValue: string | undefined, credentials: EvalCredentials | undefined): boolean;
+export declare function isTruthy(value: unknown): boolean;
+export declare function parseHeadersJson(raw: string | undefined, reportDiagnostic?: SalDiagnosticReporter): Record<string, string>;
+export declare function resolveEvalCredentials(workspaceRoot: string, reportDiagnostic?: SalDiagnosticReporter): EvalCredentials | undefined;
+export declare function normalizeExperimentId(experimentId?: string): string | undefined;
+export declare function resolveSalSidecarDir(workspaceRoot: string, experimentId?: string): string;
+export declare function resolveSalAbEnabled(flagValue: unknown): boolean;

package/dist/extensions/builtin/sal/sal-config.js

@@ -0,0 +1 @@
+var i=Object.defineProperty;var n=(e,r)=>i(e,"name",{value:r,configurable:!0});import{join as _}from"node:path";import{loadBuildMeta as a,loadInsforgeCredentials as c}from"../../../core/platform/telemetry/index.js";const l="CATUI_SAL_AB",N="CATUI_EVAL_ENABLED",x="CATUI_EVAL_ENDPOINT",C="CATUI_EVAL_RUN_ID",T="CATUI_EVAL_VARIANT",S="CATUI_EVAL_LEGACY_FILE",m="CATUI_EVAL_API_KEY",U="CATUI_EVAL_API_KEY_HEADER",u="CATUI_EVAL_HEADERS_JSON",L="CATUI_EVAL_CREDENTIALS_FILE",g="CATUI_EVAL_CLEANUP_STALE_RUNS";function p(){return a()}n(p,"loadBuildMeta");const D=p();function v(e,r){return e!==void 0?s(e):r?.cleanup_stale_runs===!0}n(v,"resolveStaleCleanupEnabled");function s(e){return e===!0?!0:typeof e!="string"||!e?!1:["1","true","yes","on"].includes(e.toLowerCase())}n(s,"isTruthy");function y(e,r){if(!e)return{};try{const t=JSON.parse(e);if(!t||typeof t!="object")return{};const o={};for(const[A,E]of Object.entries(t))typeof E=="string"&&(o[A]=E);return o}catch{return r?.({source:"sal.eval",severity:"warning",category:"config",message:`SAL eval ignored invalid JSON in ${u}.`,fingerprint:"sal.eval:config:invalid-headers-json"}),{}}}n(y,"parseHeadersJson");function R(e,r){const t=process.env[L];return c(e,"sal.eval",r,t)??void 0}n(R,"resolveEvalCredentials");function f(e){const r=(e??"").trim();return r?r.replace(/[^a-zA-Z0-9-_/.\s]/g," ").replace(/[\/\s]+/g,"-").replace(/-+/g,"-").replace(/^-|-$/g,"").toLowerCase()||"run":void 0}n(f,"normalizeExperimentId");function P(e,r){const t=f(r);return t?_(e,".memory-experiments","runs",t,"sal","anchors"):_(e,".memory-experiments","sal","anchors")}n(P,"resolveSalSidecarDir");function B(e){return s(e)||s(process.env[l])}n(B,"resolveSalAbEnabled");export{D as BUILD_META,m as EVAL_API_KEY_ENV,U as EVAL_API_KEY_HEADER_ENV,L as EVAL_CREDENTIALS_FILE_ENV,N as EVAL_ENABLED_ENV,x as EVAL_ENDPOINT_ENV,u as EVAL_HEADERS_JSON_ENV,S as EVAL_LEGACY_FILE_ENV,C as EVAL_RUN_ID_ENV,g as EVAL_STALE_CLEANUP_ENV,T as EVAL_VARIANT_ENV,l as SAL_AB_ENV,s as isTruthy,p as loadBuildMeta,f as normalizeExperimentId,y as parseHeadersJson,R as resolveEvalCredentials,B as resolveSalAbEnabled,P as resolveSalSidecarDir,v as resolveStaleCleanupEnabled};

package/dist/extensions/builtin/sal/sal-context.d.ts

@@ -0,0 +1,11 @@
+/**
+ * [WHO]: Provides SAL system-prompt context injection and sidecar turn-record persistence
+ * [FROM]: Depends on node fs/path, SAL anchors, terrain snapshots, and SalRuntime state
+ * [TO]: Consumed by extensions/builtin/sal/index.ts during before_agent_start and agent_end hooks
+ * [HERE]: extensions/builtin/sal/sal-context.ts - context formatting and local sidecar persistence for Structural Anchor Localization
+ */
+import type { AnchorResolution } from "./anchors.js";
+import type { TerrainSnapshot } from "./terrain.js";
+import type { SalRuntime } from "./sal-runtime.js";
+export declare function buildContextInjection(resolution: AnchorResolution, snapshot: TerrainSnapshot): string | undefined;
+export declare function persistTurnRecord(runtime: SalRuntime, taskRes: AnchorResolution | undefined, actionRes: AnchorResolution): void;

package/dist/extensions/builtin/sal/sal-context.js

@@ -0,0 +1,2 @@
+var p=Object.defineProperty;var a=(e,t)=>p(e,"name",{value:t,configurable:!0});import{existsSync as g,mkdirSync as m,writeFileSync as S}from"node:fs";import{join as y}from"node:path";const A=800,f=.25;function P(e){return Math.ceil(e.length*f)}a(P,"approxTokens");function k(e,t){const n=[];let o=0;for(const i of e){const s=P(i);if(o+s>t){const d=Math.max(0,t-o);if(d>20){const u=Math.floor(d/f);n.push(`${i.slice(0,u)}...`)}break}n.push(i),o+=s}return n.join(`
+`)}a(k,"truncateForBudget");function O(e,t){if(!e.selected||e.candidates.length===0)return;const n=e.candidates[0],o=n.anchor,s=`Likely task region: ${o.modulePath||o.filePath||"<root>"} (confidence ${o.confidence.toFixed(2)})`,d=n.reasons.slice(0,3).map(r=>`  - ${r}`),u=e.candidates.slice(1,4).map(r=>`  - ${r.anchor.modulePath||r.anchor.filePath||"<root>"} (${r.score.toFixed(2)})`),h=t.nodes.find(r=>(r.kind==="module"||r.kind==="root")&&(r.modulePath??"")===(o.modulePath??"")),l=h?.p2Summary?`Module brief: ${h.p2Summary}`:void 0,c=["[SAL Anchor]",s];return l&&c.push(l),d.length>0&&(c.push("Evidence:"),c.push(...d)),u.length>0&&(c.push("Alternative anchors:"),c.push(...u)),c.push("Use this anchor as a structural prior. If the prompt actually targets a different region, override it from tool evidence."),k(c,A)}a(O,"buildContextInjection");function x(e){if(!g(e.sidecarDir))try{m(e.sidecarDir,{recursive:!0})}catch{}}a(x,"ensureSidecarDir");function E(e,t,n){x(e);const o=new Date().toISOString().replace(/[:.]/g,"-"),i=y(e.sidecarDir,`turn-${o}.json`),s={generatedAt:new Date().toISOString(),workspaceRoot:e.workspaceRoot,weightsSource:e.weightsSource,prompt:e.turn.prompt?.slice(0,500),taskAnchor:t?.selected,taskCandidates:t?.candidates.slice(0,3),taskUnresolved:t?.unresolvedSignals,actionAnchor:n.selected,actionCandidates:n.candidates.slice(0,3),touchedFiles:Array.from(e.turn.touchedFiles)};try{S(i,JSON.stringify(s,null,2),"utf-8")}catch{}}a(E,"persistTurnRecord");export{O as buildContextInjection,E as persistTurnRecord};

package/dist/extensions/builtin/sal/sal-runtime.d.ts

@@ -0,0 +1,72 @@
+/**
+ * [WHO]: Provides BuildMeta, ToolCallRecord, TurnState, SalDiagnosticReporter, SalRuntime shared contracts for the SAL extension
+ * [FROM]: Depends on eval sink types, SAL anchors/terrain/weights types for runtime state shape
+ * [TO]: Consumed by extensions/builtin/sal/index.ts plus SAL config, trace, and context helpers
+ * [HERE]: extensions/builtin/sal/sal-runtime.ts - runtime contract boundary for Structural Anchor Localization modules, including per-turn loop outcome state
+ */
+import type { CreateEvalSinkOptions, EvalAdapterId, EvalSink, EvalVariant } from "./eval/index.js";
+import type { AgentRunResult } from "@catui/agent-core";
+import type { AnchorResolution } from "./anchors.js";
+import type { TerrainSnapshot } from "./terrain.js";
+import type { SalWeights } from "./weights.js";
+export interface BuildMeta {
+    version: string;
+    commitHash?: string;
+    branch?: string;
+}
+export interface ToolCallRecord {
+    toolCallId: string;
+    tool: string;
+    startMs: number;
+    endMs?: number;
+    isError?: boolean;
+}
+export interface TurnState {
+    turnId: number;
+    startedAtMs: number;
+    taskResolution?: AnchorResolution;
+    agentResult?: AgentRunResult;
+    touchedFiles: Set<string>;
+    toolCalls: ToolCallRecord[];
+    prompt?: string;
+}
+export type SalDiagnosticReporter = NonNullable<CreateEvalSinkOptions["onDiagnostic"]>;
+export interface SalRuntime {
+    workspaceRoot: string;
+    snapshot?: TerrainSnapshot;
+    snapshotErrored?: boolean;
+    /**
+     * In-flight terrain build. Deduplicates concurrent ensureSnapshot callers so
+     * we never kick off two scans at once (e.g. a prewarm and the first turn).
+     */
+    snapshotPromise?: Promise<TerrainSnapshot | undefined>;
+    weights: SalWeights;
+    weightsSource: string;
+    turn: TurnState;
+    sidecarDir: string;
+    evalSink: EvalSink;
+    evalAdapter?: EvalAdapterId;
+    evalEndpoint?: string;
+    evalApiKey?: string;
+    evalAnonKey?: string;
+    evalApiKeyHeader?: string;
+    evalHeaders: Record<string, string>;
+    evalAllowSelfSigned: boolean;
+    evalEnabled: boolean;
+    evalRunId: string;
+    evalVariantOverride?: EvalVariant;
+    evalStartedAtMs: number;
+    evalRunStarted: boolean;
+    turnCounter: number;
+    allowStaleCleanup: boolean;
+    evalMetadata: {
+        workspace_root: string;
+        session_id: string;
+        model?: string;
+    };
+    buildMeta: BuildMeta;
+    staleCleanupDone: boolean;
+    /** Set by before_agent_start when --sal-rebuild-terrain is active; consumed by agent_end. */
+    pendingRebuild: boolean;
+    reportDiagnostic: SalDiagnosticReporter;
+}

package/dist/extensions/builtin/sal/sal-trace.d.ts

@@ -0,0 +1,11 @@
+/**
+ * [WHO]: Provides SAL tool-path extraction, task intent inference, and bounded tool_trace payload construction
+ * [FROM]: Depends on node path helpers and terrain path normalization
+ * [TO]: Consumed by extensions/builtin/sal/index.ts and SAL tool trace tests
+ * [HERE]: extensions/builtin/sal/sal-trace.ts - per-turn tool and loop-outcome analytics boundary for Structural Anchor Localization
+ */
+import type { TurnState } from "./sal-runtime.js";
+export type TaskIntent = "fix" | "feat" | "refactor" | "explain" | "explore" | "unknown";
+export declare function extractToolFilePaths(toolName: string, args: unknown, workspaceRoot: string): string[];
+export declare function inferIntent(prompt: string): TaskIntent;
+export declare function buildToolTracePayload(turn: TurnState, turnDuration: number): Record<string, unknown>;

package/dist/extensions/builtin/sal/sal-trace.js

@@ -0,0 +1 @@
+var u=Object.defineProperty;var p=(t,n)=>u(t,"name",{value:n,configurable:!0});import{isAbsolute as m,join as d,relative as _}from"node:path";import{toPosixPath as h}from"./terrain.js";const g=32,b=16;function f(t,n){if(!n)return;const l=m(n)?n:d(t,n),o=_(t,l);if(!(o.startsWith("..")||o===""))return h(o)}p(f,"workspaceRelativePath");function w(t,n,l){if(!n||typeof n!="object")return[];const o=n,c=[],a=[];if(typeof o.file_path=="string"&&a.push(o.file_path),typeof o.path=="string"&&a.push(o.path),Array.isArray(o.paths))for(const r of o.paths)typeof r=="string"&&a.push(r);for(const r of a){const i=f(l,r);i&&c.push(i)}if(t==="bash"&&typeof o.command=="string"){const r=o.command.match(/[\w./-]+\.(?:ts|tsx|js|jsx|md|json)/g)??[];for(const i of r){const e=f(l,i);e&&c.push(e)}}return c}p(w,"extractToolFilePaths");const x=[["fix",[/\b(fix|bug|error|issue|broken|crash|fail|wrong|debug|patch|repair)\b/i,/(修复|报错|问题|异常|崩溃|失败|错误)/]],["refactor",[/\b(refactor|rename|extract|move|split|merge|clean\s?up|restructure)\b/i,/(重构|整理|拆分|重命名|抽取)/]],["explain",[/\b(explain|how does|what is|why does|understand|read|review|audit|tell me|describe)\b/i,/(解释|为什么|怎么|什么|看一下|看下|评审|核审|说明)/]],["feat",[/\b(add|implement|create|build|new|feature|support|enable|integrate)\b/i,/(增加|新增|实现|添加|功能|支持|接入)/]],["explore",[/\b(find|search|look for|where|locate|explore|check|investigate|list)\b/i,/(查找|找|搜|在哪|检查|排查)/]]];function M(t){if(!t||t.length<4)return"unknown";for(const[n,l]of x)for(const o of l)if(o.test(t))return n;return"unknown"}p(M,"inferIntent");function R(t,n){const l=new Map;let o=0;for(const e of t.toolCalls){const s=l.get(e.tool)??{count:0,errors:0,totalMs:0,completed:0};s.count+=1,e.isError&&(s.errors+=1,o+=1),e.endMs!=null&&(s.totalMs+=e.endMs-e.startMs,s.completed+=1),l.set(e.tool,s)}const c=Array.from(l.entries()).sort((e,s)=>s[1].count-e[1].count||e[0].localeCompare(s[0])).slice(0,b).map(([e,s])=>({tool:e,count:s.count,errors:s.errors,avg_ms:s.completed>0?Math.round(s.totalMs/s.completed):null,completed_calls:s.completed})),a=t.toolCalls.slice(0,g).map(e=>e.tool),r=t.toolCalls.filter(e=>e.endMs!=null).length,i={turn_id:t.turnId,tool_calls:c,tool_sequence:a,task_signals:{prompt_length:(t.prompt??"").length,has_error_trace:/\b(error|exception|stack\s?trace|traceback|panic)\b/i.test(t.prompt??""),has_file_reference:/[\w./-]+\.(ts|tsx|js|jsx|py|go|rs|md|json)/.test(t.prompt??""),intent:M(t.prompt??"")},has_tool_usage:t.toolCalls.length>0,total_tool_calls:t.toolCalls.length,total_errors:o,completed_tool_calls:r,truncated_tool_calls:Math.max(0,t.toolCalls.length-a.length),truncated_tool_summary:Math.max(0,l.size-c.length),duration_ms:n};return t.agentResult&&(i.agent_loop={stop_reason:t.agentResult.stopReason,turn_count:t.agentResult.turnCount,tool_call_count:t.agentResult.toolCallCount,duration_ms:t.agentResult.durationMs,permission_denial_count:t.agentResult.permissionDenialCount??0,last_transition_reason:t.agentResult.lastTransition?.reason}),i}p(R,"buildToolTracePayload");export{R as buildToolTracePayload,w as extractToolFilePaths,M as inferIntent};

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

@@ -0,0 +1,73 @@
+/**
+ * [WHO]: TerrainNode, TerrainEdge, TerrainSnapshot, buildTerrainIndex(), checkDipCoverage(), CoverageReport
+ * [FROM]: Depends on node:fs/promises, node:path
+ * [TO]: Consumed by extensions/builtin/sal/anchors.ts, extensions/builtin/sal/index.ts
+ * [HERE]: extensions/builtin/sal/terrain.ts - terrain graph builder from DIP P2/P3 headers
+ */
+export type TerrainNodeKind = "root" | "module" | "file";
+export interface TerrainNode {
+    id: string;
+    kind: TerrainNodeKind;
+    label: string;
+    modulePath?: string;
+    filePath?: string;
+    p3Who?: string;
+    p3From?: string;
+    p3To?: string;
+    p3Here?: string;
+    hasP3: boolean;
+    p2Summary?: string;
+    mtimeMs: number;
+}
+export interface TerrainEdge {
+    fromId: string;
+    toId: string;
+    type: "contains" | "adjacent-to";
+}
+export interface TerrainSnapshot {
+    workspaceRoot: string;
+    generatedAt: number;
+    nodes: TerrainNode[];
+    edges: TerrainEdge[];
+    moduleByFile: Record<string, string>;
+}
+export interface CoverageReport {
+    module: string;
+    totalFiles: number;
+    filesWithP3: number;
+    coveragePct: number;
+    hasP2: boolean;
+    missingFields: number;
+}
+/**
+ * Build a terrain index from a workspace root.
+ * Coarse, file/module-level only. Symbol-level deferred.
+ *
+ * Async by design: walks the filesystem and reads DIP headers without blocking
+ * the Node event loop, so TUI render frames (e.g. the user's message bubble
+ * queued via process.nextTick right before session.prompt()) can flush between
+ * fs operations. A synchronous implementation holds stdout long enough that
+ * GPU block terminals (Warp) coalesce a whole turn into a single block and
+ * only render it when the turn ends.
+ */
+export declare function buildTerrainIndex(workspaceRoot: string): Promise<TerrainSnapshot>;
+/**
+ * Check DIP coverage for the requested module list.
+ * Each module string is a posix-style path relative to workspace root, e.g. "core/runtime".
+ * If modules is empty, all known modules are reported.
+ */
+export declare function checkDipCoverage(snapshot: TerrainSnapshot, modules: string[]): CoverageReport[];
+/**
+ * Determine whether the snapshot is stale relative to current DIP files.
+ * Returns true when any AGENT.md (or legacy CLAUDE.md) or source file mtime exceeds snapshot.generatedAt.
+ *
+ * Async to avoid blocking the event loop during the staleness probe that runs
+ * at the top of every before_agent_start hook.
+ */
+export declare function isSnapshotStale(snapshot: TerrainSnapshot): Promise<boolean>;
+/**
+ * Look up the module id that contains a given relative file path.
+ * Used by action evidence accumulation to map touched files back to anchors.
+ */
+export declare function moduleIdForPath(snapshot: TerrainSnapshot, relPath: string): string | undefined;
+export declare function toPosixPath(p: string): string;

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

@@ -0,0 +1,3 @@
+var W=Object.defineProperty;var m=(e,o)=>W(e,"name",{value:o,configurable:!0});import{readdir as F,readFile as I,stat as x}from"node:fs/promises";import{join as y,relative as E,sep as S}from"node:path";async function M(){await new Promise(e=>setImmediate(e))}m(M,"yieldToEventLoop");const k=new Set(["node_modules",".git","dist","build",".next",".cache","coverage",".memory-experiments",".catui",".catui","out",".turbo"]),O=new Set([".ts",".tsx",".js",".jsx",".mts",".cts"]),D=["AGENT.md","CLAUDE.md"];function T(e){for(const o of D)if(e===o||e.endsWith(`/${o}`))return o}m(T,"dipModuleMapFileName");function b(e){return e.split(S).join("/")}m(b,"toPosix");async function v(e){const o=[],l=[],r=[e];let c=0;for(;r.length>0;){const n=r.pop();if(!n)break;let i;try{i=await F(n,{withFileTypes:!0})}catch{continue}const s=[];for(const u of i)if(!(u.name.startsWith(".")&&u.name!=="."&&(u.isDirectory()&&k.has(u.name)||u.isDirectory()))){if(u.isDirectory()){if(k.has(u.name))continue;const t=y(n,u.name),f=b(E(e,t));s.push(x(t).then(d=>{l.push({abs:t,rel:f,mtimeMs:d.mtimeMs}),r.push(t)},()=>{l.push({abs:t,rel:f,mtimeMs:0}),r.push(t)}))}else if(u.isFile()){const t=y(n,u.name),f=b(E(e,t));s.push(x(t).then(d=>{o.push({abs:t,rel:f,mtimeMs:d.mtimeMs})},()=>{o.push({abs:t,rel:f,mtimeMs:0})}))}}await Promise.all(s),++c%16===0&&await M()}return{files:o,dirs:l}}m(v,"walkAsync");const L=/\/\*\*([\s\S]*?)\*\//;function N(e){const o=e.match(L);if(!o)return;const l=o[1];if(!/\[WHO\]|\[FROM\]|\[TO\]|\[HERE\]/.test(l))return;const r=l.split(`
+`).map(i=>i.replace(/^\s*\*\s?/,"").trim()),c={};let n;for(const i of r){const s=i.match(/^\[(WHO|FROM|TO|HERE)\]:\s*(.*)$/);s?(n=s[1].toLowerCase(),c[n]=s[2].trim()):n&&i.length>0&&(c[n]=`${c[n]??""} ${i}`.trim())}return c}m(N,"parseP3Header");function R(e){const o=e.split(`
+`);let l=!1;const r=[];for(const c of o){if(/^##\s+Overview/i.test(c)){l=!0;continue}if(l&&(/^##\s+/.test(c)||(c.trim().length>0&&r.push(c.trim()),r.join(" ").length>400)))break}if(r.length>0)return r.join(" ").slice(0,400);for(const c of o){const n=c.trim();if(n&&!(n.startsWith("#")||n.startsWith(">")))return n.slice(0,400)}}m(R,"parseP2Summary");async function H(e){const{files:o}=await v(e),l=[],r=[],c={},n=new Map,i=[];let s=0;for(const t of o){const f=T(t.rel);if(!f)continue;const d=t.rel===f?"":t.rel.slice(0,t.rel.length-f.length-1);let a;try{const P=await I(t.abs,"utf-8");a=R(P)}catch{}const h=d||"<root>",p={id:h,kind:d?"module":"root",label:d||"<root>",modulePath:d||void 0,p2Summary:a,hasP3:!1,mtimeMs:t.mtimeMs};n.set(h,p),l.push(p),++s%32===0&&await M()}let u=0;for(const t of o){const f=t.rel.lastIndexOf(".");if(f<0)continue;const d=t.rel.slice(f);if(!O.has(d))continue;let a;try{const w=await I(t.abs,"utf-8");a=N(w)}catch{}let h="<root>",p=-1;for(const w of n.values()){const g=w.modulePath??"";g===""&&p<0&&(h="<root>"),g&&t.rel.startsWith(`${g}/`)&&g.length>p&&(h=w.id,p=g.length)}const P={id:t.rel,kind:"file",label:t.rel,modulePath:n.get(h)?.modulePath,filePath:t.rel,p3Who:a?.who,p3From:a?.from,p3To:a?.to,p3Here:a?.here,hasP3:!!a,mtimeMs:t.mtimeMs};i.push(P),l.push(P),c[P.id]=h,r.push({fromId:h,toId:P.id,type:"contains"}),++u%32===0&&await M()}return{workspaceRoot:e,generatedAt:Date.now(),nodes:l,edges:r,moduleByFile:c}}m(H,"buildTerrainIndex");function j(e,o){const l=[],r=o.length>0?o:null,c=e.nodes.filter(i=>i.kind==="module"||i.kind==="root").map(i=>i.modulePath??""),n=r??c;for(const i of n){const s=e.nodes.find(a=>(a.kind==="module"||a.kind==="root")&&(a.modulePath??"")===i),u=e.nodes.filter(a=>a.kind==="file"&&(a.modulePath??"")===i),t=u.length,f=u.filter(a=>a.hasP3).length,d=u.filter(a=>a.hasP3&&(!a.p3Who||!a.p3From||!a.p3To||!a.p3Here)).length;l.push({module:i||"<root>",totalFiles:t,filesWithP3:f,coveragePct:t===0?0:Math.round(f/t*1e3)/10,hasP2:!!s,missingFields:d})}return l}m(j,"checkDipCoverage");async function B(e){const o=[e.workspaceRoot];let l=0;for(;o.length>0;){const r=o.pop();if(!r)break;let c;try{c=await F(r,{withFileTypes:!0})}catch{continue}const n=[];for(const s of c){if(s.isDirectory()){if(k.has(s.name)||s.name.startsWith("."))continue;o.push(y(r,s.name));continue}if(!s.isFile())continue;const u=D.includes(s.name),t=s.name.lastIndexOf("."),f=t>=0?s.name.slice(t):"";!u&&!O.has(f)||n.push(y(r,s.name))}const i=await Promise.all(n.map(s=>x(s).then(u=>u.mtimeMs,()=>0)));for(const s of i)if(s>e.generatedAt)return!0;++l%16===0&&await M()}return!1}m(B,"isSnapshotStale");function $(e,o){const l=b(o);if(e.moduleByFile[l])return e.moduleByFile[l];let r,c=-1;for(const n of e.nodes){if(n.kind!=="module")continue;const i=n.modulePath??"";i&&l.startsWith(`${i}/`)&&i.length>c&&(r=n.id,c=i.length)}return r}m($,"moduleIdForPath");function U(e){return b(e)}m(U,"toPosixPath");export{H as buildTerrainIndex,j as checkDipCoverage,B as isSnapshotStale,$ as moduleIdForPath,U as toPosixPath};

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

@@ -0,0 +1,28 @@
+/**
+ * [WHO]: SalWeights interface, SAL_DEFAULT_WEIGHTS, loadSalWeights()
+ * [FROM]: Depends on node:fs, node:path
+ * [TO]: Consumed by extensions/builtin/sal/anchors.ts and extensions/builtin/sal/index.ts
+ * [HERE]: extensions/builtin/sal/weights.ts - tunable scoring weight loader
+ */
+export interface SalWeights {
+    directFileEvidence: number;
+    moduleResponsibilityMatch: number;
+    dipContractMatch: number;
+    importNeighborhoodMatch: number;
+    memoryHistoryMatch: number;
+    semanticScore: number;
+    recencyScore: number;
+    importanceScore: number;
+    structuralSalience: number;
+    proceduralApplicability: number;
+}
+export declare const SAL_DEFAULT_WEIGHTS: SalWeights;
+/**
+ * Load SalWeights from sal-config.json adjacent to the memory directory or project root.
+ * Falls back to defaults if file is missing or invalid. Unknown fields are ignored;
+ * missing fields fall back individually to defaults.
+ */
+export declare function loadSalWeights(searchDirs: string[]): {
+    weights: SalWeights;
+    source: string;
+};

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

@@ -0,0 +1 @@
+var p=Object.defineProperty;var s=(t,o)=>p(t,"name",{value:o,configurable:!0});import{existsSync as u,readFileSync as f}from"node:fs";import{join as l}from"node:path";const c={directFileEvidence:.4,moduleResponsibilityMatch:.2,dipContractMatch:.15,importNeighborhoodMatch:.15,memoryHistoryMatch:.1,semanticScore:.25,recencyScore:.15,importanceScore:.15,structuralSalience:.3,proceduralApplicability:.15};function S(t){for(const o of t){const r=l(o,"sal-config.json");if(u(r))try{const a=f(r,"utf-8"),d=JSON.parse(a),i={...c};for(const n of Object.keys(c)){const e=d[n];typeof e=="number"&&Number.isFinite(e)&&e>=0&&(i[n]=e)}return{weights:i,source:r}}catch{}}return{weights:{...c},source:"default"}}s(S,"loadSalWeights");export{c as SAL_DEFAULT_WEIGHTS,S as loadSalWeights};