@ngockhoale/ukit 1.5.24 → 1.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "1.5.24",
+  "version": "1.6.1",
   "description": "Install/update an index-first AI workspace for Claude Code, Antigravity, OpenAI Codex, and OpenCode.",
   "license": "MIT",
   "type": "module",

package/src/core/compact/threshold.js

@@ -6,8 +6,9 @@ import { compactContextBlock } from './index.js';
 const DEFAULT_MAX_PROMPT_ENTRIES = 12;
 const DEFAULT_MAX_OUTPUT_ENTRIES = 12;
 const DEFAULT_HISTORY_LAYER_COUNT = 2;
-const SOFT_RELEASE_RATIO = 0.9;
+const SOFT_RELEASE_RATIO = 0.6;
 const HARD_RELEASE_RATIO = 0.92;
+const COMPACT_RELEASE_TARGET = 30_000;
 const PHASE_COOLDOWN_MS = {
   soft: 5 * 60 * 1000,
   hard: 10 * 60 * 1000,
@@ -414,15 +415,20 @@ function computeEstimatedTotalTokens({
   recentOutputs = [],
   estimatedContextTokens = 0,
   baselineTokens = 0,
+  sessionTokens = 0,
 }) {
   const promptTokens = recentPrompts.reduce((sum, entry) => sum + finiteNumber(entry.tokens, 0), 0);
   const outputTokens = recentOutputs.reduce((sum, entry) => sum + finiteNumber(entry.tokensBefore ?? entry.tokens, 0), 0);
-  return baselineTokens + estimatedContextTokens + promptTokens + outputTokens;
+  const windowTokens = promptTokens + outputTokens;
+  // sessionTokens accumulates across all prompts/outputs (beyond the recent window)
+  // include only the excess over the recent window to avoid double-counting
+  const sessionExcess = Math.max(0, finiteNumber(sessionTokens, 0) - windowTokens);
+  return baselineTokens + estimatedContextTokens + windowTokens + sessionExcess;
 }
 
 export function buildCompactThresholds(config = {}) {
-  const softThreshold = Math.max(1, finiteNumber(config?.compact?.tokenThreshold, 100_000));
-  const hardThreshold = Math.max(softThreshold + 1, Math.round(softThreshold * 1.2));
+  const softThreshold = Math.max(1, finiteNumber(config?.compact?.tokenThreshold, 50_000));
+  const hardThreshold = Math.max(softThreshold + 1, Math.round(softThreshold * 1.6));
   const baselineTokens = Math.max(120, Math.min(18_000, Math.round(softThreshold * 0.18)));
 
   return {
@@ -551,7 +557,7 @@ export function buildCompactPressureState(rawState = null, config = {}) {
     thresholds.softThreshold = rawSoftThreshold;
     thresholds.hardThreshold = rawHardThreshold > rawSoftThreshold
       ? rawHardThreshold
-      : Math.max(rawSoftThreshold + 1, Math.round(rawSoftThreshold * 1.2));
+      : Math.max(rawSoftThreshold + 1, Math.round(rawSoftThreshold * 1.6));
     thresholds.baselineTokens = Math.max(120, Math.min(18_000, Math.round(thresholds.softThreshold * 0.18)));
   }
   const recentPrompts = (Array.isArray(rawState?.recentPrompts) ? rawState.recentPrompts : [])
@@ -565,6 +571,7 @@ export function buildCompactPressureState(rawState = null, config = {}) {
     .sort((left, right) => (right.timestamp ?? 0) - (left.timestamp ?? 0))
     .slice(0, DEFAULT_MAX_OUTPUT_ENTRIES);
   const estimatedContextTokens = computeEstimatedContextTokens(rawState);
+  const sessionTokens = Math.max(0, finiteNumber(rawState?.sessionTokens, 0));
   const estimatedTotalTokens = finiteNumber(
     rawState?.estimatedTotalTokens,
     computeEstimatedTotalTokens({
@@ -572,6 +579,7 @@ export function buildCompactPressureState(rawState = null, config = {}) {
       recentOutputs,
       estimatedContextTokens,
       baselineTokens: thresholds.baselineTokens,
+      sessionTokens,
     }),
   );
   const releaseThresholds = buildReleaseThresholds(thresholds);
@@ -589,6 +597,7 @@ export function buildCompactPressureState(rawState = null, config = {}) {
     hardReleaseThreshold: releaseThresholds.hardReleaseThreshold,
     baselineTokens: thresholds.baselineTokens,
     estimatedContextTokens,
+    sessionTokens,
     estimatedTotalTokens,
     phase: resolveCompactPhase(estimatedTotalTokens, thresholds, rawState),
     taskMode,
@@ -617,9 +626,10 @@ export function registerPromptPressure(state, {
     return current;
   }
 
+  const promptTokenCount = estimateTokenCount(normalizedPrompt);
   const entry = normalizePromptEntry({
     timestamp,
-    tokens: estimateTokenCount(normalizedPrompt),
+    tokens: promptTokenCount,
     summary: summarizePromptText(normalizedPrompt, routingContext),
     targetFile: routingContext?.targetFile ?? null,
     taskType: routingContext?.taskType ?? null,
@@ -636,6 +646,7 @@ export function registerPromptPressure(state, {
     updatedAt: timestamp,
     routingContext,
     recentPrompts,
+    sessionTokens: current.sessionTokens + promptTokenCount,
     estimatedTotalTokens: undefined,
     estimatedContextTokens: estimateTokenCount([
       routeSummary?.line ?? '',
@@ -666,12 +677,13 @@ export function registerOutputPressure(state, {
     return current;
   }
 
+  const normalizedTokensBefore = Math.max(1, finiteNumber(tokensBefore, estimateTokenCount(summary || normalizedSummary)));
   const entry = normalizeOutputEntry({
     timestamp,
     command,
     profile,
     exitCode,
-    tokensBefore: Math.max(1, finiteNumber(tokensBefore, estimateTokenCount(summary || normalizedSummary))),
+    tokensBefore: normalizedTokensBefore,
     tokensAfter: Math.max(1, finiteNumber(tokensAfter, estimateTokenCount(normalizedSummary))),
     savedTokens: Math.max(0, finiteNumber(savedTokens, 0)),
     summary: normalizedSummary,
@@ -685,6 +697,7 @@ export function registerOutputPressure(state, {
     ...current,
     updatedAt: timestamp,
     recentOutputs,
+    sessionTokens: current.sessionTokens + normalizedTokensBefore,
     estimatedTotalTokens: undefined,
     taskMode: deriveTaskMode({
       routingContext: current.routingContext ?? {},
@@ -755,9 +768,19 @@ export function registerThresholdCompactPlan(state, plan, config = {}) {
     stats.softHits += 1;
   }
 
+  // Decay sessionTokens on hard compact plan: cap at COMPACT_RELEASE_TARGET for large sessions,
+  // or fall back to recent-window tokens when already below the release target
+  const windowTokens = current.recentPrompts.reduce((sum, entry) => sum + finiteNumber(entry.tokens, 0), 0)
+    + current.recentOutputs.reduce((sum, entry) => sum + finiteNumber(entry.tokensBefore ?? entry.tokens, 0), 0);
+  const decayTarget = current.sessionTokens > COMPACT_RELEASE_TARGET ? COMPACT_RELEASE_TARGET : windowTokens;
+  const decayedSessionTokens = normalizePhase(plan.phase) === 'hard'
+    ? Math.min(current.sessionTokens, decayTarget)
+    : current.sessionTokens;
+
   return buildCompactPressureState({
     ...current,
     updatedAt: now,
+    sessionTokens: decayedSessionTokens,
     cooldownUntil: now + resolvePhaseCooldownMs(plan.phase),
     historyLayers: uniqueStrings(plan.layers ?? []).slice(0, DEFAULT_HISTORY_LAYER_COUNT),
     latestPlan: {

package/src/core/runtimeConfig.js

@@ -58,7 +58,7 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
     },
     compact: {
       enabled: true,
-      tokenThreshold: 100_000,
+      tokenThreshold: 50_000,
       contextRotDetection: true,
       askBeforeDrop: true,
       agentContext: {

package/templates/.claude/ukit/index/route-task.mjs

@@ -433,6 +433,9 @@ function printRouteState(state) {
     console.log(`recent-output: ${recentOutputDisplay}`);
   }
   console.log(`summary: ${compactSummary}`);
+  if (state.routeSummary?.executionContract?.modelTier) {
+    console.log(`modelTier: ${state.routeSummary.executionContract.modelTier}`);
+  }
   if (nextDisplay) {
     console.log(`next: ${nextDisplay}`);
   }
@@ -1655,6 +1658,7 @@ function buildExecutionContract(executionMode = null) {
 
   const contracts = {
     'tiny-fix': {
+      modelTier: 'lite',
       maxReadPasses: 0,
       maxContextPulls: 0,
       verificationPolicy: 'minimal-or-targeted',
@@ -1663,6 +1667,7 @@ function buildExecutionContract(executionMode = null) {
       completionEvidence: ['write-evidence'],
     },
     'local-fix': {
+      modelTier: 'code',
       maxReadPasses: 1,
       maxContextPulls: 1,
       verificationPolicy: 'targeted-if-covered',
@@ -1671,6 +1676,7 @@ function buildExecutionContract(executionMode = null) {
       completionEvidence: ['write-evidence'],
     },
     'local-build': {
+      modelTier: 'code',
       maxReadPasses: 2,
       maxContextPulls: 1,
       verificationPolicy: 'targeted-if-covered',
@@ -1679,6 +1685,7 @@ function buildExecutionContract(executionMode = null) {
       completionEvidence: ['write-evidence'],
     },
     'find-cause': {
+      modelTier: 'smart',
       maxReadPassesBeforeReassess: 3,
       verificationPolicy: 'root-cause-then-targeted',
       completionRule: 'never-claim-fixed-without-write-and-verification',
@@ -1686,6 +1693,7 @@ function buildExecutionContract(executionMode = null) {
       completionEvidence: ['write-evidence', 'verification-evidence'],
     },
     'shared-edit': {
+      modelTier: 'code',
       maxReadPasses: 2,
       maxContextPulls: 2,
       verificationPolicy: 'targeted-then-widen-on-risk',
@@ -1695,6 +1703,7 @@ function buildExecutionContract(executionMode = null) {
       mirrorConsistencyRequired: true,
     },
     'map-impact': {
+      modelTier: 'smart',
       maxReadPasses: 3,
       maxContextPulls: 3,
       verificationPolicy: 'impact-first-then-targeted-then-widen-on-risk',
@@ -1704,6 +1713,7 @@ function buildExecutionContract(executionMode = null) {
       mirrorConsistencyRequired: true,
     },
     'review-release': {
+      modelTier: 'smart',
       verificationPolicy: 'evidence-first',
       completionRule: 'report-findings-not-implementation',
       delegationPolicy: 'allow-review-sidecar',

package/templates/.claude/ukit/runtime/compact-threshold.mjs

@@ -13,8 +13,9 @@ import {
 const DEFAULT_MAX_PROMPT_ENTRIES = 12;
 const DEFAULT_MAX_OUTPUT_ENTRIES = 12;
 const DEFAULT_HISTORY_LAYER_COUNT = 2;
-const SOFT_RELEASE_RATIO = 0.9;
+const SOFT_RELEASE_RATIO = 0.6;
 const HARD_RELEASE_RATIO = 0.92;
+const COMPACT_RELEASE_TARGET = 30_000;
 const PHASE_COOLDOWN_MS = {
   soft: 5 * 60 * 1000,
   hard: 10 * 60 * 1000,
@@ -421,15 +422,20 @@ function computeEstimatedTotalTokens({
   recentOutputs = [],
   estimatedContextTokens = 0,
   baselineTokens = 0,
+  sessionTokens = 0,
 }) {
   const promptTokens = recentPrompts.reduce((sum, entry) => sum + finiteNumber(entry.tokens, 0), 0);
   const outputTokens = recentOutputs.reduce((sum, entry) => sum + finiteNumber(entry.tokensBefore ?? entry.tokens, 0), 0);
-  return baselineTokens + estimatedContextTokens + promptTokens + outputTokens;
+  const windowTokens = promptTokens + outputTokens;
+  // sessionTokens accumulates across all prompts/outputs (beyond the recent window)
+  // include only the excess over the recent window to avoid double-counting
+  const sessionExcess = Math.max(0, finiteNumber(sessionTokens, 0) - windowTokens);
+  return baselineTokens + estimatedContextTokens + windowTokens + sessionExcess;
 }
 
 export function buildCompactThresholds(config = {}) {
-  const softThreshold = Math.max(1, finiteNumber(config?.compact?.tokenThreshold, 100_000));
-  const hardThreshold = Math.max(softThreshold + 1, Math.round(softThreshold * 1.2));
+  const softThreshold = Math.max(1, finiteNumber(config?.compact?.tokenThreshold, 50_000));
+  const hardThreshold = Math.max(softThreshold + 1, Math.round(softThreshold * 1.6));
   const baselineTokens = Math.max(120, Math.min(18_000, Math.round(softThreshold * 0.18)));
 
   return {
@@ -558,7 +564,7 @@ export function buildCompactPressureState(rawState = null, config = {}) {
     thresholds.softThreshold = rawSoftThreshold;
     thresholds.hardThreshold = rawHardThreshold > rawSoftThreshold
       ? rawHardThreshold
-      : Math.max(rawSoftThreshold + 1, Math.round(rawSoftThreshold * 1.2));
+      : Math.max(rawSoftThreshold + 1, Math.round(rawSoftThreshold * 1.6));
     thresholds.baselineTokens = Math.max(120, Math.min(18_000, Math.round(thresholds.softThreshold * 0.18)));
   }
   const recentPrompts = (Array.isArray(rawState?.recentPrompts) ? rawState.recentPrompts : [])
@@ -572,6 +578,7 @@ export function buildCompactPressureState(rawState = null, config = {}) {
     .sort((left, right) => (right.timestamp ?? 0) - (left.timestamp ?? 0))
     .slice(0, DEFAULT_MAX_OUTPUT_ENTRIES);
   const estimatedContextTokens = computeEstimatedContextTokens(rawState);
+  const sessionTokens = Math.max(0, finiteNumber(rawState?.sessionTokens, 0));
   const estimatedTotalTokens = finiteNumber(
     rawState?.estimatedTotalTokens,
     computeEstimatedTotalTokens({
@@ -579,6 +586,7 @@ export function buildCompactPressureState(rawState = null, config = {}) {
       recentOutputs,
       estimatedContextTokens,
       baselineTokens: thresholds.baselineTokens,
+      sessionTokens,
     }),
   );
   const releaseThresholds = buildReleaseThresholds(thresholds);
@@ -596,6 +604,7 @@ export function buildCompactPressureState(rawState = null, config = {}) {
     hardReleaseThreshold: releaseThresholds.hardReleaseThreshold,
     baselineTokens: thresholds.baselineTokens,
     estimatedContextTokens,
+    sessionTokens,
     estimatedTotalTokens,
     phase: resolveCompactPhase(estimatedTotalTokens, thresholds, rawState),
     taskMode,
@@ -624,9 +633,10 @@ export function registerPromptPressure(state, {
     return current;
   }
 
+  const promptTokenCount = estimateTokenCount(normalizedPrompt);
   const entry = normalizePromptEntry({
     timestamp,
-    tokens: estimateTokenCount(normalizedPrompt),
+    tokens: promptTokenCount,
     summary: summarizePromptText(normalizedPrompt, routingContext),
     targetFile: routingContext?.targetFile ?? null,
     taskType: routingContext?.taskType ?? null,
@@ -643,6 +653,7 @@ export function registerPromptPressure(state, {
     updatedAt: timestamp,
     routingContext,
     recentPrompts,
+    sessionTokens: current.sessionTokens + promptTokenCount,
     estimatedTotalTokens: undefined,
     estimatedContextTokens: estimateTokenCount([
       routeSummary?.line ?? '',
@@ -673,12 +684,13 @@ export function registerOutputPressure(state, {
     return current;
   }
 
+  const normalizedTokensBefore = Math.max(1, finiteNumber(tokensBefore, estimateTokenCount(summary || normalizedSummary)));
   const entry = normalizeOutputEntry({
     timestamp,
     command,
     profile,
     exitCode,
-    tokensBefore: Math.max(1, finiteNumber(tokensBefore, estimateTokenCount(summary || normalizedSummary))),
+    tokensBefore: normalizedTokensBefore,
     tokensAfter: Math.max(1, finiteNumber(tokensAfter, estimateTokenCount(normalizedSummary))),
     savedTokens: Math.max(0, finiteNumber(savedTokens, 0)),
     summary: normalizedSummary,
@@ -692,6 +704,7 @@ export function registerOutputPressure(state, {
     ...current,
     updatedAt: timestamp,
     recentOutputs,
+    sessionTokens: current.sessionTokens + normalizedTokensBefore,
     estimatedTotalTokens: undefined,
     taskMode: deriveTaskMode({
       routingContext: current.routingContext ?? {},
@@ -762,9 +775,19 @@ export function registerThresholdCompactPlan(state, plan, config = {}) {
     stats.softHits += 1;
   }
 
+  // Decay sessionTokens on hard compact plan: cap at COMPACT_RELEASE_TARGET for large sessions,
+  // or fall back to recent-window tokens when already below the release target
+  const windowTokens = current.recentPrompts.reduce((sum, entry) => sum + finiteNumber(entry.tokens, 0), 0)
+    + current.recentOutputs.reduce((sum, entry) => sum + finiteNumber(entry.tokensBefore ?? entry.tokens, 0), 0);
+  const decayTarget = current.sessionTokens > COMPACT_RELEASE_TARGET ? COMPACT_RELEASE_TARGET : windowTokens;
+  const decayedSessionTokens = normalizePhase(plan.phase) === 'hard'
+    ? Math.min(current.sessionTokens, decayTarget)
+    : current.sessionTokens;
+
   return buildCompactPressureState({
     ...current,
     updatedAt: now,
+    sessionTokens: decayedSessionTokens,
     cooldownUntil: now + resolvePhaseCooldownMs(plan.phase),
     historyLayers: uniqueStrings(plan.layers ?? []).slice(0, DEFAULT_HISTORY_LAYER_COUNT),
     latestPlan: {

package/templates/CLAUDE.md

@@ -136,6 +136,32 @@ Khi Handoff mode: đọc `docs/AI_HANDOFF/RULES.md` để biết 4 phase (Idea+P
 - `autonomy.level` in `.ukit/storage/config.json` controls how much UKit acts without asking first: `conservative` (ask more), `balanced` (default), `free-run` (auto-run more).
 - End users should not need to change this; maintainers may tune it per-project.
 
+## 3-Tier Model Routing
+
+**Internal orchestration only — end users still just use natural language. No new commands.**
+
+UKit routes tasks to one of three model tiers based on task complexity:
+
+| Tier | Generic alias | Claude model | Typical tasks |
+|------|--------------|--------------|---------------|
+| lite | `unic-lite` | claude-haiku | Reads, git queries, bash summaries, small doc edits |
+| code | `unic-code` | claude-sonnet | Normal coding, local fixes, shared edits, builds |
+| smart | `unic-smart` | claude-opus | Deep reasoning, root-cause analysis, release review |
+
+### Contract-to-tier mapping
+
+| Contract | Tier |
+|----------|------|
+| `tiny-fix` | lite |
+| `local-fix`, `local-build`, `shared-edit` | code |
+| `find-cause`, `map-impact`, `review-release` | smart |
+
+### Escalation rule
+
+When the same file or symbol fails `debugLoopThreshold` (default: 2) times in one session, UKit routes the next attempt one tier higher (capped at `smart`). Config: `orchestration.escalation` in `.ukit/storage/config.json`.
+
+This is internal orchestration — end users do not need to know about tiers, thresholds, or escalation. The AI handles routing transparently.
+
 ## Project Snapshot
 
 - Project: {{project.name}} | Root: {{project.root}}

package/templates/ukit/storage/config.json

@@ -8,7 +8,7 @@
   },
   "compact": {
     "enabled": true,
-    "tokenThreshold": 100000,
+    "tokenThreshold": 50000,
     "contextRotDetection": true,
     "askBeforeDrop": true,
     "codexContext": {