smart-context-mcp 1.16.2 → 1.16.5

package/README.md

@@ -56,7 +56,7 @@ Restart your AI client. Done.
 # Check installed version
 npm list -g smart-context-mcp
 
-# Should show: smart-context-mcp@1.16.2 (or later)
+# Should show: smart-context-mcp@1.16.5 (or later)
 
 # Update to latest version
 npm update -g smart-context-mcp

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "smart-context-mcp",
   "mcpName": "io.github.Arrayo/smart-context-mcp",
-  "version": "1.16.2",
+  "version": "1.16.5",
   "description": "MCP server that reduces agent token usage by 90% with intelligent context compression, task checkpoint persistence, and workflow-aware agent guidance.",
   "author": "Francisco Caballero Portero <fcp1978@hotmail.com>",
   "type": "module",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/Arrayo/smart-context-mcp",
     "source": "github"
   },
-  "version": "1.16.2",
+  "version": "1.16.5",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "smart-context-mcp",
-      "version": "1.16.2",
+      "version": "1.16.5",
       "transport": {
         "type": "stdio"
       },

package/src/client-contract.js

@@ -74,11 +74,17 @@ export const buildOperationalContextLines = (
   const summary = result?.summary;
   const continuityState = result?.continuity?.state;
   const storageIssue = result?.storageHealth?.issue;
+  const task = result?.task ?? null;
+  const handoff = result?.handoff ?? null;
 
   if (result?.found && summary) {
     const label = sessionStart ? 'resume' : continuityState ?? 'resume';
     lines.push(`devctx ${label}: session ${result.sessionId}`);
 
+    if (task?.taskId) {
+      lines.push(`task: ${truncate(task.taskId, maxLineLength)}`);
+    }
+
     if (summary.goal) {
       lines.push(`goal: ${truncate(summary.goal, maxLineLength)}`);
     }
@@ -106,10 +112,20 @@ export const buildOperationalContextLines = (
     lines.push(`devctx new task session: ${truncate(summary.goal, maxLineLength)}`);
   }
 
-  if (result?.continuity?.reason) {
+  if (!mutationSafety?.blocked && result?.continuity?.reason) {
     lines.push(`context status: ${truncate(result.continuity.reason, maxLineLength)}`);
   }
 
+  if (handoff?.fromAgentId || handoff?.summary?.nextStep || handoff?.summary?.pending?.length > 0) {
+    lines.push(`handoff: ${truncate(`from ${handoff?.fromAgentId ?? 'previous agent'} via ${handoff?.trigger ?? 'handoff'}`, maxLineLength)}`);
+    if (handoff?.summary?.pending?.[0]) {
+      lines.push(`pending: ${truncate(handoff.summary.pending[0], maxLineLength)}`);
+    }
+    if (handoff?.summary?.nextStep) {
+      lines.push(`handoff next: ${truncate(handoff.summary.nextStep, maxLineLength)}`);
+    }
+  }
+
   if (mutationSafety?.blocked) {
     const reasons = mutationSafety.blockedBy?.join(' and ') || 'blocked';
     lines.push(`repo safety: ${mutationSafety.stateDbPath} is ${reasons}; context writes are blocked.`);

package/src/orchestration/adapters/claude-adapter.js

@@ -7,7 +7,9 @@ import { smartTurn } from '../../tools/smart-turn.js';
 import {
   deleteHookTurnState,
   getHookTurnState,
+  persistTaskHandoff,
   setHookTurnState,
+  upsertAgentRun,
 } from '../../storage/sqlite.js';
 import { DEFAULT_START_MAX_TOKENS, resolveManagedStart } from '../base-orchestrator.js';
 import { extractNextStep, normalizeWhitespace, truncate } from '../policy/event-policy.js';
@@ -25,8 +27,20 @@ export const WRITE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit']);
 
 const uniq = (values) => [...new Set(values.filter((value) => typeof value === 'string' && value.trim().length > 0))];
 
+const resolveAgentId = (input = {}) => {
+  const value = input.agent_id ?? input.agentId ?? input.assistant_id ?? input.worker_id ?? null;
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : 'main';
+};
+
+const resolveParentAgentId = (input = {}) => {
+  const value = input.parent_agent_id ?? input.parentAgentId ?? null;
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+};
+
 export const buildClaudeHookKey = ({ sessionId, agentId = null }) =>
-  agentId ? `${HOOK_CLIENT}:subagent:${sessionId}:${agentId}` : `${HOOK_CLIENT}:main:${sessionId}`;
+  agentId && agentId !== 'main'
+    ? `${HOOK_CLIENT}:subagent:${sessionId}:${agentId}`
+    : `${HOOK_CLIENT}:main:${sessionId}`;
 
 const countPromptTerms = (value) =>
   normalizeWhitespace(value)
@@ -148,6 +162,8 @@ export const createClaudeAdapter = ({
   summaryTool = smartSummary,
   resolveStart = resolveManagedStart,
   persistMetric = persistMetrics,
+  writeAgentRun = upsertAgentRun,
+  writeTaskHandoff = persistTaskHandoff,
   getMutationSafety = getRepoMutationSafety,
   readHookState = null,
   writeHookState = ({ hookKey, state }) => setHookTurnState({ hookKey, state }),
@@ -215,7 +231,11 @@ export const createClaudeAdapter = ({
   const maybeTrackTurn = async ({
     hookKey,
     claudeSessionId,
+    conversationId,
     projectSessionId,
+    taskId,
+    agentId,
+    parentAgentId,
     prompt,
     continuityState,
   }) => {
@@ -232,7 +252,11 @@ export const createClaudeAdapter = ({
       state: {
         client: HOOK_CLIENT,
         claudeSessionId,
+        conversationId,
         projectSessionId,
+        taskId,
+        agentId,
+        parentAgentId,
         turnId: `${claudeSessionId}:${Date.now()}`,
         promptPreview: truncate(prompt, MAX_PROMPT_PREVIEW),
         continuityState,
@@ -246,6 +270,45 @@ export const createClaudeAdapter = ({
     });
   };
 
+  const maybeAutoCheckpointFromState = async (state, { trigger = 'post_tool_use' } = {}) => {
+    if (!state?.projectSessionId || getMutationSafety().shouldBlock) {
+      return false;
+    }
+
+    const update = {
+      ...(state.promptPreview ? { currentFocus: state.promptPreview } : {}),
+      ...(state.touchedFiles.length > 0 ? { touchedFiles: state.touchedFiles } : {}),
+    };
+
+    await summaryTool({
+      action: 'checkpoint',
+      sessionId: state.projectSessionId,
+      event: 'milestone',
+      update,
+      maxTokens: STOP_MAX_TOKENS,
+      force: true,
+    });
+
+    if (state.taskId) {
+      await writeTaskHandoff({
+        taskId: state.taskId,
+        sessionId: state.projectSessionId,
+        fromAgentId: state.agentId ?? null,
+        toAgentId: null,
+        trigger,
+        summary: {
+          currentFocus: state.promptPreview,
+          touchedFiles: state.touchedFiles,
+          pending: [],
+          nextStep: null,
+          evidence: state.touchedFiles.length > 0 ? [`Touched files: ${state.touchedFiles.join(', ')}`] : [],
+        },
+      });
+    }
+
+    return true;
+  };
+
   const handleSessionStart = async () => {
     const result = await startTurn({
       phase: 'start',
@@ -262,6 +325,8 @@ export const createClaudeAdapter = ({
   };
 
   const handleUserPromptSubmit = async (input) => {
+    const agentId = resolveAgentId(input);
+    const parentAgentId = resolveParentAgentId(input);
     const startResolution = await resolveStart({
       prompt: input.prompt,
       ensureSession: true,
@@ -272,10 +337,27 @@ export const createClaudeAdapter = ({
     });
     const result = startResolution.startResult;
 
+    if (!getMutationSafety().shouldBlock) {
+      await writeAgentRun({
+        runId: buildClaudeHookKey({ sessionId: input.session_id, agentId }),
+        taskId: result.task?.taskId ?? null,
+        agentId,
+        parentAgentId,
+        client: HOOK_CLIENT,
+        conversationId: input.session_id,
+        sessionId: result.sessionId ?? null,
+        role: agentId === 'main' ? 'main' : 'subagent',
+      });
+    }
+
     const trackedState = await maybeTrackTurn({
-      hookKey: buildClaudeHookKey({ sessionId: input.session_id }),
+      hookKey: buildClaudeHookKey({ sessionId: input.session_id, agentId }),
       claudeSessionId: input.session_id,
+      conversationId: input.session_id,
       projectSessionId: result.sessionId ?? null,
+      taskId: result.task?.taskId ?? null,
+      agentId,
+      parentAgentId,
       prompt: input.prompt,
       continuityState: result.continuity?.state ?? '',
     });
@@ -291,7 +373,7 @@ export const createClaudeAdapter = ({
   };
 
   const handlePostToolUse = async (input) => {
-    const hookKey = buildClaudeHookKey({ sessionId: input.session_id });
+    const hookKey = buildClaudeHookKey({ sessionId: input.session_id, agentId: resolveAgentId(input) });
     const existing = await readTrackedState(hookKey);
     if (!existing) {
       return null;
@@ -307,7 +389,7 @@ export const createClaudeAdapter = ({
       toolResponse: input.tool_response,
     });
 
-    const nextState = {
+    let nextState = {
       ...existing,
       checkpointed: checkpoint.matched ? true : existing.checkpointed,
       checkpointEvent: checkpoint.matched ? checkpoint.event : existing.checkpointEvent,
@@ -316,6 +398,17 @@ export const createClaudeAdapter = ({
       updatedAt: new Date().toISOString(),
     };
 
+    if (!checkpoint.matched && touchedFiles.length > 0) {
+      const autoCheckpointed = await maybeAutoCheckpointFromState(nextState, { trigger: 'post_tool_use' });
+      if (autoCheckpointed) {
+        nextState = {
+          ...nextState,
+          checkpointed: true,
+          checkpointEvent: 'milestone',
+        };
+      }
+    }
+
     await maybeSetTrackedTurnState({ hookKey, state: nextState });
     if (checkpoint.matched || touchedFiles.length > 0) {
       await recordHookMetrics({
@@ -329,7 +422,7 @@ export const createClaudeAdapter = ({
   };
 
   const handleStop = async (input) => {
-    const hookKey = buildClaudeHookKey({ sessionId: input.session_id });
+    const hookKey = buildClaudeHookKey({ sessionId: input.session_id, agentId: resolveAgentId(input) });
     const state = await readTrackedState(hookKey);
     if (!state) {
       return null;
@@ -371,6 +464,23 @@ export const createClaudeAdapter = ({
         });
       }
 
+      if (state.taskId) {
+        await writeTaskHandoff({
+          taskId: state.taskId,
+          sessionId: state.projectSessionId,
+          fromAgentId: state.agentId ?? null,
+          toAgentId: null,
+          trigger: state.agentId && state.agentId !== 'main' ? 'subagent_delegate' : 'stop',
+          summary: {
+            currentFocus: update.currentFocus ?? state.promptPreview,
+            touchedFiles: state.touchedFiles,
+            pending: update.nextStep ? [update.nextStep] : [],
+            nextStep: update.nextStep ?? null,
+            evidence: state.touchedFiles.length > 0 ? [`Touched files: ${state.touchedFiles.join(', ')}`] : [],
+          },
+        });
+      }
+
       await recordHookMetrics({
         action: 'Stop',
         sessionId: state.projectSessionId,

package/src/orchestration/adapters/cursor-adapter.js

@@ -7,7 +7,9 @@ import { smartTurn } from '../../tools/smart-turn.js';
 import {
   deleteHookTurnState,
   getHookTurnState,
+  persistTaskHandoff,
   setHookTurnState,
+  upsertAgentRun,
 } from '../../storage/sqlite.js';
 import { DEFAULT_START_MAX_TOKENS, resolveManagedStart } from '../base-orchestrator.js';
 import { extractNextStep, normalizeWhitespace, truncate } from '../policy/event-policy.js';
@@ -25,8 +27,20 @@ export const WRITE_TOOLS = new Set(['Write', 'StrReplace', 'Delete', 'EditNotebo
 
 const uniq = (values) => [...new Set(values.filter((value) => typeof value === 'string' && value.trim().length > 0))];
 
+const resolveAgentId = (input = {}) => {
+  const value = input.agent_id ?? input.agentId ?? input.worker_id ?? null;
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : 'main';
+};
+
+const resolveParentAgentId = (input = {}) => {
+  const value = input.parent_agent_id ?? input.parentAgentId ?? null;
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+};
+
 export const buildCursorHookKey = ({ conversationId, agentId = null }) =>
-  agentId ? `${HOOK_CLIENT}:subagent:${conversationId}:${agentId}` : `${HOOK_CLIENT}:main:${conversationId}`;
+  agentId && agentId !== 'main'
+    ? `${HOOK_CLIENT}:subagent:${conversationId}:${agentId}`
+    : `${HOOK_CLIENT}:main:${conversationId}`;
 
 const countPromptTerms = (value) =>
   normalizeWhitespace(value)
@@ -151,6 +165,8 @@ export const createCursorAdapter = ({
   summaryTool = smartSummary,
   resolveStart = resolveManagedStart,
   persistMetric = persistMetrics,
+  writeAgentRun = upsertAgentRun,
+  writeTaskHandoff = persistTaskHandoff,
   getMutationSafety = getRepoMutationSafety,
   readHookState = null,
   writeHookState = ({ hookKey, state }) => setHookTurnState({ hookKey, state }),
@@ -218,7 +234,11 @@ export const createCursorAdapter = ({
   const maybeTrackTurn = async ({
     hookKey,
     cursorConversationId,
+    conversationId,
     projectSessionId,
+    taskId,
+    agentId,
+    parentAgentId,
     prompt,
     continuityState,
   }) => {
@@ -235,7 +255,11 @@ export const createCursorAdapter = ({
       state: {
         client: HOOK_CLIENT,
         cursorConversationId,
+        conversationId,
         projectSessionId,
+        taskId,
+        agentId,
+        parentAgentId,
         turnId: `${cursorConversationId}:${Date.now()}`,
         promptPreview: truncate(prompt, MAX_PROMPT_PREVIEW),
         continuityState,
@@ -249,6 +273,45 @@ export const createCursorAdapter = ({
     });
   };
 
+  const maybeAutoCheckpointFromState = async (state, { trigger = 'post_tool_use' } = {}) => {
+    if (!state?.projectSessionId || getMutationSafety().shouldBlock) {
+      return false;
+    }
+
+    const update = {
+      ...(state.promptPreview ? { currentFocus: state.promptPreview } : {}),
+      ...(state.touchedFiles.length > 0 ? { touchedFiles: state.touchedFiles } : {}),
+    };
+
+    await summaryTool({
+      action: 'checkpoint',
+      sessionId: state.projectSessionId,
+      event: 'milestone',
+      update,
+      maxTokens: STOP_MAX_TOKENS,
+      force: true,
+    });
+
+    if (state.taskId) {
+      await writeTaskHandoff({
+        taskId: state.taskId,
+        sessionId: state.projectSessionId,
+        fromAgentId: state.agentId ?? null,
+        toAgentId: null,
+        trigger,
+        summary: {
+          currentFocus: state.promptPreview,
+          touchedFiles: state.touchedFiles,
+          pending: [],
+          nextStep: null,
+          evidence: state.touchedFiles.length > 0 ? [`Touched files: ${state.touchedFiles.join(', ')}`] : [],
+        },
+      });
+    }
+
+    return true;
+  };
+
   const handleConversationStart = async () => {
     const result = await startTurn({
       phase: 'start',
@@ -265,6 +328,8 @@ export const createCursorAdapter = ({
   };
 
   const handleUserMessageSubmit = async (input) => {
+    const agentId = resolveAgentId(input);
+    const parentAgentId = resolveParentAgentId(input);
     const startResolution = await resolveStart({
       prompt: input.user_message,
       ensureSession: true,
@@ -275,10 +340,27 @@ export const createCursorAdapter = ({
     });
     const result = startResolution.startResult;
 
+    if (!getMutationSafety().shouldBlock) {
+      await writeAgentRun({
+        runId: buildCursorHookKey({ conversationId: input.conversation_id, agentId }),
+        taskId: result.task?.taskId ?? null,
+        agentId,
+        parentAgentId,
+        client: HOOK_CLIENT,
+        conversationId: input.conversation_id,
+        sessionId: result.sessionId ?? null,
+        role: agentId === 'main' ? 'main' : 'subagent',
+      });
+    }
+
     const trackedState = await maybeTrackTurn({
-      hookKey: buildCursorHookKey({ conversationId: input.conversation_id }),
+      hookKey: buildCursorHookKey({ conversationId: input.conversation_id, agentId }),
       cursorConversationId: input.conversation_id,
+      conversationId: input.conversation_id,
       projectSessionId: result.sessionId ?? null,
+      taskId: result.task?.taskId ?? null,
+      agentId,
+      parentAgentId,
       prompt: input.user_message,
       continuityState: result.continuity?.state ?? '',
     });
@@ -294,7 +376,7 @@ export const createCursorAdapter = ({
   };
 
   const handlePostToolUse = async (input) => {
-    const hookKey = buildCursorHookKey({ conversationId: input.conversation_id });
+    const hookKey = buildCursorHookKey({ conversationId: input.conversation_id, agentId: resolveAgentId(input) });
     const existing = await readTrackedState(hookKey);
     if (!existing) {
       return null;
@@ -310,7 +392,7 @@ export const createCursorAdapter = ({
       toolResponse: input.tool_response,
     });
 
-    const nextState = {
+    let nextState = {
       ...existing,
       checkpointed: checkpoint.matched ? true : existing.checkpointed,
       checkpointEvent: checkpoint.matched ? checkpoint.event : existing.checkpointEvent,
@@ -319,6 +401,17 @@ export const createCursorAdapter = ({
       updatedAt: new Date().toISOString(),
     };
 
+    if (!checkpoint.matched && touchedFiles.length > 0) {
+      const autoCheckpointed = await maybeAutoCheckpointFromState(nextState, { trigger: 'post_tool_use' });
+      if (autoCheckpointed) {
+        nextState = {
+          ...nextState,
+          checkpointed: true,
+          checkpointEvent: 'milestone',
+        };
+      }
+    }
+
     await maybeSetTrackedTurnState({ hookKey, state: nextState });
     if (checkpoint.matched || touchedFiles.length > 0) {
       await recordHookMetrics({
@@ -332,7 +425,7 @@ export const createCursorAdapter = ({
   };
 
   const handleConversationEnd = async (input) => {
-    const hookKey = buildCursorHookKey({ conversationId: input.conversation_id });
+    const hookKey = buildCursorHookKey({ conversationId: input.conversation_id, agentId: resolveAgentId(input) });
     const state = await readTrackedState(hookKey);
     if (!state) {
       return null;
@@ -374,6 +467,23 @@ export const createCursorAdapter = ({
         });
       }
 
+      if (state.taskId) {
+        await writeTaskHandoff({
+          taskId: state.taskId,
+          sessionId: state.projectSessionId,
+          fromAgentId: state.agentId ?? null,
+          toAgentId: null,
+          trigger: state.agentId && state.agentId !== 'main' ? 'subagent_delegate' : 'session_end',
+          summary: {
+            currentFocus: update.currentFocus ?? state.promptPreview,
+            touchedFiles: state.touchedFiles,
+            pending: update.nextStep ? [update.nextStep] : [],
+            nextStep: update.nextStep ?? null,
+            evidence: state.touchedFiles.length > 0 ? [`Touched files: ${state.touchedFiles.join(', ')}`] : [],
+          },
+        });
+      }
+
       await recordHookMetrics({
         action: 'ConversationEnd',
         sessionId: state.projectSessionId,

package/src/server.js

@@ -35,6 +35,17 @@ import {
 const require = createRequire(import.meta.url);
 const { version } = require('../package.json');
 
+const SERVER_INSTRUCTIONS = `devctx — compressed context, search, and session handoff for long work (migrations, multi-file refactors, multi-session tasks).
+
+smart_turn (session continuity — read this before calling):
+- START: phase "start". Pass userPrompt (current goal). ensureSession true recommended when you want persistence. Use at the beginning of substantial work or when resuming after a break — not for one-line fixes or single-shot questions.
+- END: phase "end". Pass event: milestone | blocker | task_complete. Pass sessionId if you have it; include update (nextStep, completed, etc.) when checkpointing progress. Call after a meaningful slice of work (close a phase), not after every trivial edit.
+- SKIP smart_turn entirely for trivial or same-session point tasks (the tool schema also warns about this).
+
+Source of truth: devctx does not replace git history, PRs, or repo docs (e.g. MIGRATION.md). If end was not called or work was not committed, those remain authoritative.
+
+Other entry points: smart_context for curated multi-file context; smart_search with intent for exploration; smart_read in outline|signatures|symbol before full reads; smart_shell for safe git/npm diagnostics.`;
+
 export const asTextResult = (result) => ({
   content: [
     {
@@ -52,10 +63,10 @@ export const createDevctxServer = () => {
     process.exit(1);
   }
 
-  const server = new McpServer({
-    name: 'devctx',
-    version,
-  });
+  const server = new McpServer(
+    { name: 'devctx', version },
+    { instructions: SERVER_INSTRUCTIONS },
+  );
 
   setServerForStreaming(server);