feat(agent-core-v2): meta-mark bundled skill parts and replace positional slicing

Bundled skill blocks are now constructed with meta { source: 'skill
activation' }, matching the hook-part convention. Every former
content.slice(skillActivations.length) site — turn prompt text, steer
merge/echo, session and fork titles, transcript fold, TUI replay — now
annotates then filters by meta, so prompt content no longer depends on
block positions and the loop needs no hook-part knowledge. A shared
annotate step keeps legacy wires working: leading unmarked blocks (one
per bundled activation) are marked on read before filtering.

Author: sailist

apps/kimi-code/src/tui/utils/message-replay.ts

@@ -248,6 +248,44 @@ export function isUserPromptSubmitHookPart(
   );
 }
 
+const SKILL_ACTIVATION_PART_SOURCE = 'skill activation';
+
+export function isSkillActivationPart(part: ContentPart): boolean {
+  return (
+    part.type === 'text' &&
+    (part as { meta?: { source?: unknown } }).meta?.source === SKILL_ACTIVATION_PART_SOURCE
+  );
+}
+
+function annotateBundledSkillParts(
+  content: readonly ContentPart[],
+  bundledActivations: readonly BundledSkillActivationRef[],
+): ContentPart[] {
+  if (bundledActivations.length === 0 || content.some(isSkillActivationPart)) {
+    return [...content];
+  }
+  let index = 0;
+  return content.map((part) => {
+    const activation = bundledActivations[index];
+    if (
+      activation !== undefined &&
+      part.type === 'text' &&
+      (part as { meta?: { source?: unknown } }).meta?.source === undefined
+    ) {
+      index += 1;
+      return {
+        ...part,
+        meta: { source: SKILL_ACTIVATION_PART_SOURCE, activationId: activation.activationId },
+      };
+    }
+    return part;
+  });
+}
+
+interface BundledSkillActivationRef {
+  readonly activationId: string;
+}
+
 export function withoutUserPromptSubmitHookParts(
   content: readonly ContentPart[],
 ): ContentPart[] {
@@ -321,13 +359,15 @@ export function bundledSkillsFromOrigin(
 }
 
 /**
- * Content parts the caller actually typed: the engine prepends one rendered
- * text part per bundled skill, so the caller's own parts start right after
- * them.
+ * Content parts the caller actually typed: skill blocks are meta-marked at
+ * construction; legacy wires carry no marks, so the leading unmarked parts
+ * (one per bundled activation) are annotated first, then filtered out.
  */
 export function stripBundledSkillParts(message: ContextMessage): readonly ContentPart[] {
-  const bundledCount = bundledSkillsFromOrigin(message.origin).length;
-  return bundledCount === 0 ? message.content : message.content.slice(bundledCount);
+  return annotateBundledSkillParts(
+    message.content,
+    bundledSkillsFromOrigin(message.origin),
+  ).filter((part) => !isSkillActivationPart(part));
 }
 
 export function pluginCommandFromOrigin(

apps/kimi-code/test/tui/kimi-tui-message-flow.test.ts

@@ -1015,7 +1015,11 @@ describe('KimiTUI message flow', () => {
               message: {
                 role: 'user',
                 content: [
-                  { type: 'text', text: 'skill card C body' },
+                  {
+                    type: 'text',
+                    text: 'skill card C body',
+                    meta: { source: 'skill activation', activationId: 'act-3' },
+                  },
                   { type: 'text', text: 'please /commit' },
                 ],
                 toolCalls: [],

packages/agent-core-v2/docs/state-manifest.d.ts

@@ -727,6 +727,8 @@ export interface AgentStateSnapshot {
       meta?: /* TextPartMeta — packages/agent-core-v2/src/human/llm/message.ts */ {
         source?: string;
         contentType?: string;
+        activationId?: string;
+        [key: string]: unknown;
       };
     } | /* ThinkPart — packages/agent-core-v2/src/human/llm/message.ts */ {
       type: 'think';
@@ -1041,6 +1043,8 @@ export interface AgentStateSnapshot {
     meta?: /* TextPartMeta — packages/agent-core-v2/src/human/llm/message.ts */ {
       source?: string;
       contentType?: string;
+      activationId?: string;
+      [key: string]: unknown;
     };
   } | /* ThinkPart — packages/agent-core-v2/src/human/llm/message.ts */ {
     type: 'think';

packages/agent-core-v2/src/agent/loop/turnEvents.ts

@@ -2,7 +2,7 @@
 import { z } from 'zod';
 
 import type { PromptOrigin } from '#/agent/contextMemory/types';
-import { isUserPromptSubmitHookPart } from '#/agent/contextMemory/hookParts';
+import { annotateBundledSkillParts, isSkillActivationPart } from '#human/agent/origin';
 import { parseDaemonFileUrl } from '#/agent/media/mediaRef';
 import { AgentEvent2, registerEvent2Class } from '#/app/event/event2';
 import type { FinishReason } from '#human/llm/finish-reason';
@@ -50,10 +50,10 @@ export function turnPromptText(
   input: readonly ContentPart[],
   origin?: PromptOrigin,
 ): string | undefined {
-  const bundledBlocks = origin?.kind === 'user' ? (origin.skillActivations?.length ?? 0) : 0;
-  const parts = input.filter((part): part is TextPart => part.type === 'text');
-  const callerParts = parts.filter((part) => !isUserPromptSubmitHookPart(part));
-  const text = [...parts.filter(isUserPromptSubmitHookPart), ...callerParts.slice(bundledBlocks)]
+  const bundledActivations =
+    origin?.kind === 'user' ? (origin.skillActivations ?? []) : [];
+  const text = annotateBundledSkillParts(input, bundledActivations)
+    .filter((part): part is TextPart => part.type === 'text' && !isSkillActivationPart(part))
     .map((part) => part.text)
     .join('');
   return text.length > 0 ? text : undefined;

packages/agent-core-v2/src/features/skill/skillService.ts

@@ -13,6 +13,7 @@ import { IEventService } from '#/app/event/event';
 import { ITelemetryService } from '#/app/telemetry/telemetry';
 import { ErrorCodes, Error2 } from '#/errors';
 import type { ContentPart } from '#human/llm/message';
+import { skillActivationPart } from '#human/agent/origin';
 import { MAIN_AGENT_ID } from '#/session/agentLifecycle/agentLifecycle';
 import { ISessionContext } from '#/session/sessionContext/sessionContext';
 import { ISessionMetadata } from '#/session/sessionMetadata/sessionMetadata';
@@ -204,9 +205,10 @@ export class AgentSkillService implements IAgentSkillService {
 
     const skillArgs = input.args ?? '';
     const skillContent = this.renderSkillPrompt(skill, skillArgs);
+    const activationId = randomUUID();
     const origin: SkillActivationOrigin = {
       kind: 'skill_activation',
-      activationId: randomUUID(),
+      activationId,
       skillName: skill.name,
       trigger: 'user-slash',
       skillType: skill.metadata.type,
@@ -216,16 +218,16 @@ export class AgentSkillService implements IAgentSkillService {
     };
     return {
       origin,
-      part: {
-        type: 'text',
-        text: renderUserSlashSkillPrompt({
+      part: skillActivationPart(
+        renderUserSlashSkillPrompt({
           skillName: skill.name,
           skillArgs,
           skillContent,
           skillSource: skill.source,
           skillDir: skill.dir,
         }),
-      },
+        activationId,
+      ),
       entry: {
         activationId: origin.activationId,
         skillName: origin.skillName,

packages/agent-core-v2/src/human/agent/historySchema.ts

@@ -6,9 +6,7 @@ import type { HistoryMessage } from './turn';
 const textPartSchema = z.object({
   type: z.literal('text'),
   text: z.string(),
-  meta: z
-    .looseObject({ source: z.string().optional(), contentType: z.string().optional() })
-    .optional(),
+  meta: z.record(z.string(), z.unknown()).optional(),
 });
 const thinkPartSchema = z.object({
   type: z.literal('think'),

packages/agent-core-v2/src/human/agent/origin.ts

@@ -1,5 +1,36 @@
 import { promptDisplayTextFromContentParts } from '../../agent/prompt/promptMetadataText';
-import type { ContentPart } from '#/llm/message';
+import type { ContentPart, TextPart } from '#/llm/message';
+
+export const SKILL_ACTIVATION_PART_SOURCE = 'skill activation';
+
+export function skillActivationPart(text: string, activationId: string): TextPart {
+  return { type: 'text', text, meta: { source: SKILL_ACTIVATION_PART_SOURCE, activationId } };
+}
+
+export function isSkillActivationPart(part: ContentPart): boolean {
+  return part.type === 'text' && part.meta?.source === SKILL_ACTIVATION_PART_SOURCE;
+}
+
+export function annotateBundledSkillParts(
+  content: readonly ContentPart[],
+  bundledActivations: readonly BundledSkillActivation[],
+): ContentPart[] {
+  if (bundledActivations.length === 0 || content.some(isSkillActivationPart)) {
+    return [...content];
+  }
+  let index = 0;
+  return content.map((part) => {
+    const activation = bundledActivations[index];
+    if (activation !== undefined && part.type === 'text' && part.meta?.source === undefined) {
+      index += 1;
+      return {
+        ...part,
+        meta: { source: SKILL_ACTIVATION_PART_SOURCE, activationId: activation.activationId },
+      };
+    }
+    return part;
+  });
+}
 
 export type SkillSource = 'project' | 'user' | 'extra' | 'builtin';
 
@@ -43,12 +74,14 @@ function userOriginOf(origin: PromptOrigin | undefined): UserPromptOrigin | unde
   return origin !== undefined && origin.kind === 'user' ? (origin as UserPromptOrigin) : undefined;
 }
 
-function bundledSkillBlockCount(message: SteerMessage): number {
-  return userOriginOf(message.origin)?.skillActivations?.length ?? 0;
+function bundledSkillActivationsOf(message: SteerMessage): readonly BundledSkillActivation[] {
+  return userOriginOf(message.origin)?.skillActivations ?? [];
 }
 
 export function stripBundledSkillBlocks(message: SteerMessage): ContentPart[] {
-  return message.content.slice(bundledSkillBlockCount(message));
+  return annotateBundledSkillParts(message.content, bundledSkillActivationsOf(message)).filter(
+    (part) => !isSkillActivationPart(part),
+  );
 }
 
 export function mergeSteerMessages(messages: readonly SteerMessage[]): {
@@ -69,7 +102,11 @@ export function mergeSteerMessages(messages: readonly SteerMessage[]): {
   return {
     role: 'user',
     content: [
-      ...messages.flatMap((message) => message.content.slice(0, bundledSkillBlockCount(message))),
+      ...messages.flatMap((message) =>
+        annotateBundledSkillParts(message.content, bundledSkillActivationsOf(message)).filter(
+          isSkillActivationPart,
+        ),
+      ),
       ...messages.flatMap((message) => stripBundledSkillBlocks(message)),
     ],
     toolCalls: [],

packages/agent-core-v2/src/human/llm/message.ts

@@ -10,6 +10,8 @@ export type Role = 'system' | 'user' | 'assistant' | 'tool';
 export type TextPartMeta = {
   source?: string;
   contentType?: string;
+  activationId?: string;
+  [key: string]: unknown;
 };
 
 export interface TextPart {

packages/agent-core-v2/src/human/test/agent/machine.test.ts

@@ -1236,7 +1236,7 @@ describe('agent machine input.steer', () => {
     });
     expect(steered).toEqual([['p1'], ['p2', 'p3']]);
     expect(actor.getSnapshot().context.notifications[1]?.message.content).toEqual([
-      { type: 'text', text: 'SKILLBLOCK' },
+      { type: 'text', text: 'SKILLBLOCK', meta: { source: 'skill activation', activationId: 'a1' } },
       { type: 'text', text: 'p2 body' },
       { type: 'text', text: 'third' },
     ]);

packages/agent-core-v2/src/session/sessionTitle/agentTitlePromptSourceService.ts

@@ -2,6 +2,8 @@ import { ScopeActivation, registerScopedService } from '#/_base/di/scope';
 import { LifecycleScope } from '#/app/scopes';
 import { IAgentContextMemoryService } from '#/agent/contextMemory/contextMemory';
 import type { ContextMessage, PromptOrigin } from '#/agent/contextMemory/types';
+import { isUserPromptSubmitHookPart } from '#/agent/contextMemory/hookParts';
+import { annotateBundledSkillParts, isSkillActivationPart } from '#human/agent/origin';
 import { IAgentLoopService } from '#/agent/loop/loop';
 import {
   promptMetadataTextFromContentParts,
@@ -110,9 +112,12 @@ function isNaturalLanguagePrompt(message: ContextMessage): boolean {
 }
 
 function promptMetadataTextFromUserMessage(message: ContextMessage): string | undefined {
-  const bundled = message.origin?.kind === 'user' ? (message.origin.skillActivations?.length ?? 0) : 0;
+  const bundled =
+    message.origin?.kind === 'user' ? (message.origin.skillActivations ?? []) : [];
   return promptMetadataTextFromContentParts(
-    bundled === 0 ? message.content : message.content.slice(bundled),
+    annotateBundledSkillParts(message.content, bundled).filter(
+      (part) => !isSkillActivationPart(part) && !isUserPromptSubmitHookPart(part),
+    ),
     message.origin?.kind === 'user' ? message.origin.clientMetadata : undefined,
   );
 }