feat(kap-server): accept bundled skill activations on the prompt submission route

.changeset/kap-prompt-skills.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+The session prompt submission API now accepts an optional `skills` field: one or more named skills activate together with the prompt as a single bundled turn (one undo unit), validated up front with zero side effects on rejection.

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

@@ -10,7 +10,9 @@
  * the rendered skill blocks precede the caller's parts in the content and the
  * activation metadata rides the prompt's origin, so the bundle is a single
  * turn and a single undo unit), and records model-tool activations without a
- * turn (`recordModelToolActivation`). Bound at Agent scope.
+ * turn (`recordModelToolActivation`). `promptWithSkills` resolves with the
+ * queue identity of the submitted bundle (`prompt_id` / `created_at`, the
+ * launch `state`, and `turn_id` once launched). Bound at Agent scope.
  */
 
 import { createDecorator } from "#/_base/di/instantiation";
@@ -34,11 +36,18 @@ export interface PromptWithSkillsInput {
   readonly skills: readonly PromptSkillActivation[];
 }
 
+export interface PromptWithSkillsResult {
+  readonly turn_id?: number;
+  readonly prompt_id: string;
+  readonly created_at: string;
+  readonly state: 'running' | 'queued' | 'blocked';
+}
+
 export interface IAgentSkillService {
   readonly _serviceBrand: undefined;
 
   activate(input: SkillActivationInput): Promise<PromptLaunchResult>;
-  promptWithSkills(input: PromptWithSkillsInput): Promise<PromptLaunchResult | undefined>;
+  promptWithSkills(input: PromptWithSkillsInput): Promise<PromptWithSkillsResult>;
   recordModelToolActivation(origin: SkillActivationOrigin): void;
 }
 

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

@@ -40,6 +40,7 @@ import {
   IAgentSkillService,
   type PromptSkillActivation,
   type PromptWithSkillsInput,
+  type PromptWithSkillsResult,
   type SkillActivationInput,
 } from './skill';
 import { SkillActivate, skillKey } from './skillOps';
@@ -130,7 +131,7 @@ export class AgentSkillService extends Service implements IAgentSkillService {
     return { turn_id: turn.id };
   }
 
-  async promptWithSkills(input: PromptWithSkillsInput): Promise<PromptLaunchResult | undefined> {
+  async promptWithSkills(input: PromptWithSkillsInput): Promise<PromptWithSkillsResult> {
     if (input.input.length === 0) {
       throw new Error2(ErrorCodes.REQUEST_INVALID, 'promptWithSkills requires a non-empty prompt');
     }
@@ -166,9 +167,19 @@ export class AgentSkillService extends Service implements IAgentSkillService {
         },
       },
     });
-    if (handle.state === 'pending') return undefined;
+    if (handle.state === 'pending') {
+      return { prompt_id: handle.id, created_at: handle.createdAt, state: 'queued' };
+    }
     const turn = await handle.launched;
-    return turn === undefined ? undefined : { turn_id: turn.id };
+    if (turn === undefined && handle.state !== 'blocked') {
+      throw new Error2(ErrorCodes.INTERNAL, 'promptWithSkills failed to launch a turn');
+    }
+    return {
+      turn_id: turn?.id,
+      prompt_id: handle.id,
+      created_at: handle.createdAt,
+      state: handle.state === 'blocked' ? 'blocked' : 'running',
+    };
   }
 
   recordModelToolActivation(origin: SkillActivationOrigin): void {

packages/agent-core-v2/test/agent/skill/activateSkill.test.ts

@@ -89,7 +89,9 @@ describe('promptWithSkills', () => {
       input: [{ type: 'text', text: 'Review this change.' }],
       skills: [{ name: 'review' }, { name: 'security' }],
     });
-    expect(launched?.turn_id).toBe(0);
+    expect(launched.turn_id).toBe(0);
+    expect(launched.prompt_id).toBeTruthy();
+    expect(launched.state).toBe('running');
     await ctx.untilTurnEnd();
 
     expect(ctx.llmCalls).toHaveLength(1);

packages/agent-core-v2/test/harness/agent.ts

@@ -87,7 +87,7 @@ interface StopTaskPayload { readonly taskId: string; readonly reason?: string }
 interface UndoHistoryPayload { readonly count: number }
 interface UnregisterToolPayload { readonly name: string }
 import { type UsageStatus } from '#/agent/usage/usage';
-import { IAgentSkillService, type PromptWithSkillsInput, type SkillActivationInput } from '#/agent/skill/skill';
+import { IAgentSkillService, type PromptWithSkillsInput, type PromptWithSkillsResult, type SkillActivationInput } from '#/agent/skill/skill';
 import { AgentSkillService } from '#/agent/skill/skillService';
 import { IAgentRuntimeBindingSeed } from '#/agent/runtimeBinding/runtimeBinding';
 import { IAgentRuntimeService } from '#/agent/runtimeBinding/agentRuntime';
@@ -341,7 +341,7 @@ type RpcPromise<T> = Promise<T> & {
 
 interface AgentRpcPassthroughAPI {
   prompt: (payload: PromptPayload) => Promisable<PromptLaunchResult | undefined>;
-  promptWithSkills: (payload: PromptWithSkillsInput) => Promisable<PromptLaunchResult | undefined>;
+  promptWithSkills: (payload: PromptWithSkillsInput) => Promisable<PromptWithSkillsResult>;
   steer: (payload: SteerPayload) => Promisable<PromptLaunchResult | undefined>;
   cancel: (payload: CancelPayload) => void;
   undoHistory: (payload: UndoHistoryPayload) => Promisable<number>;

packages/kap-server/src/protocol/rest-prompt.ts

@@ -2,9 +2,16 @@
  *   POST /v1/sessions/{sid}/prompts
  *     Body:  PromptSubmission { content, metadata?, agent_id?, profile?, model?, thinking?,
  *              permission_mode?, plan_mode?, swarm_mode?, goal_objective?, goal_control?,
- *              disabled_tools?, prompt_id? }
+ *              disabled_tools?, prompt_id?, skills? }
  *     Reply: PromptSubmitResult { prompt_id, user_message_id, status, content, created_at }
  *
+ *     `skills` (optional, non-empty) submits a bundled skill prompt through
+ *     `IAgentSkillService.promptWithSkills`: every named skill is validated up
+ *     front (an unknown name rejects the whole submission), one `skill.activated`
+ *     event fires per skill, and the prompt enqueues as a single user message
+ *     with the rendered skill blocks preceding the caller's content — one turn,
+ *     one undo unit. Each entry is `{ name, args? }` (activation by name only).
+ *
  *   GET /v1/sessions/{sid}/prompts
  *     Reply: { active: PromptItem | null, queued: PromptItem[] }
  *
@@ -29,6 +36,12 @@ import {
 export { promptPermissionModeSchema, promptThinkingSchema };
 export type { PromptPermissionMode, PromptThinking } from '@moonshot-ai/agent-core-v2/app/sessionLegacy/sessionProtocol';
 
+export const promptSkillActivationSchema = z.object({
+  name: z.string().min(1),
+  args: z.string().optional(),
+});
+export type PromptSkillActivation = z.infer<typeof promptSkillActivationSchema>;
+
 export const promptSubmissionSchema = z.object({
   content: z.array(messageContentSchema).min(1),
   metadata: z.record(z.string(), z.unknown()).optional(),
@@ -51,6 +64,9 @@ export const promptSubmissionSchema = z.object({
   // turn's `turn.started` (`promptId`) so the submitter can bind its own
   // bookkeeping to that turn exactly. Omit to let the engine assign one.
   prompt_id: z.string().min(1).optional(),
+  // Bundled skill submission: every named skill activates with the prompt as
+  // a single bundled user message (one turn, one undo unit).
+  skills: z.array(promptSkillActivationSchema).min(1).optional(),
 });
 export type PromptSubmission = z.infer<typeof promptSubmissionSchema>;
 

packages/kap-server/src/routes/prompts.ts

@@ -14,11 +14,14 @@ import {
   IAgentProfileService,
   IAgentToolPolicyService,
   IAgentPromptService,
+  IAgentSkillService,
   IAuthSummaryService,
   IEventService,
   IFileService,
   ISessionMediaStore,
   ISessionMetadata,
+  ISessionSkillCatalog,
+  isUserActivatableSkillType,
   promptMetadataTextFromContentParts,
   ProfileError,
   type PromptHandle,
@@ -45,6 +48,7 @@ import {
   promptSteerResultSchema,
   promptSubmissionSchema,
   promptSubmitResultSchema,
+  type PromptSkillActivation,
 } from '../protocol/rest-prompt';
 import { z } from 'zod';
 
@@ -118,13 +122,42 @@ async function resolvePromptFromSession(session: ISessionScopeHandle, agentId?:
   }
   return {
     prompt: agent.accessor.get(IAgentPromptService),
+    skill: agent.accessor.get(IAgentSkillService),
+    events: agent.accessor.get(IEventService),
     auth: agent.accessor.get(IAuthSummaryService),
     profile: agent.accessor.get(IAgentProfileService),
     toolPolicy: agent.accessor.get(IAgentToolPolicyService),
     permissionMode: agent.accessor.get(IAgentPermissionModeService),
   };
 }
 
+/**
+ * Read-only pre-flight for bundled skill submissions: every named skill must
+ * exist in the session catalog and be user-activatable. Runs before any media
+ * materialization or control override, so a rejected bundle leaves the
+ * session untouched. The engine re-validates authoritatively inside
+ * `promptWithSkills`; this edge check only exists to protect side effects
+ * that precede it (media copies, persistent overrides).
+ */
+async function assertActivatableSkills(
+  catalog: ISessionSkillCatalog,
+  skills: readonly PromptSkillActivation[],
+): Promise<void> {
+  await catalog.ready;
+  for (const skill of skills) {
+    const definition = catalog.catalog.getSkill(skill.name);
+    if (definition === undefined) {
+      throw new Error2(ErrorCodes.SKILL_NOT_FOUND, `Skill "${skill.name}" was not found`);
+    }
+    if (!isUserActivatableSkillType(definition.metadata.type)) {
+      throw new Error2(
+        ErrorCodes.SKILL_TYPE_UNSUPPORTED,
+        `Skill "${definition.name}" cannot be activated by the user`,
+      );
+    }
+  }
+}
+
 /**
  * Bind the resolved agent to the profile named by a prompt submission's
  * `profile` field. First-bind semantics live in the engine: a same-name
@@ -198,6 +231,8 @@ export function registerPromptsRoutes(app: PromptRouteHost, core: Scope): void {
       success: { data: promptSubmitResultSchema },
       errors: {
         [ErrorCode.VALIDATION_FAILED]: { detailsSchema: validationDetailsSchema },
+        [ErrorCode.SKILL_NOT_FOUND]: {},
+        [ErrorCode.SKILL_NOT_ACTIVATABLE]: {},
         [ErrorCode.AUTH_PROVISIONING_REQUIRED]: {},
         [ErrorCode.AUTH_TOKEN_MISSING]: { detailsSchema: authProviderDetailsSchema },
         [ErrorCode.AUTH_TOKEN_UNAUTHORIZED]: { detailsSchema: authProviderDetailsSchema },
@@ -206,7 +241,7 @@ export function registerPromptsRoutes(app: PromptRouteHost, core: Scope): void {
         [ErrorCode.PROMPT_ID_CONFLICT]: {},
         [ErrorCode.PROMPT_ALREADY_COMPLETED]: { dataSchema: z.object({ aborted: z.literal(false) }) },
       },
-      description: 'Submit a prompt to a session',
+      description: 'Submit a prompt to a session, optionally with bundled skill activations',
       tags: ['prompts'],
       operationId: 'submitPrompt',
     },
@@ -220,7 +255,25 @@ export function registerPromptsRoutes(app: PromptRouteHost, core: Scope): void {
         // mutated: a bad `file_id` must not create the agent, register `main`
         // in session metadata, or touch the session's controls.
         await assertPromptFileRefs(req.body.content, core.accessor.get(IFileService));
+        // A cold resume loads the session but does not create the main agent;
+        // bundled-skill preflight runs at this point precisely so a rejected
+        // bundle cannot even mutate session metadata by registering `main`.
         const session = await resolveSession(core, session_id);
+        if (req.body.skills !== undefined) {
+          // A bundled submission goes through the engine's own enqueue path,
+          // which assigns the prompt id — reject the combination here, before
+          // the agent is materialized or any override binds.
+          if (req.body.prompt_id !== undefined) {
+            throw new Error2(
+              ErrorCodes.REQUEST_INVALID,
+              'prompt_id cannot be combined with a bundled skill submission',
+            );
+          }
+          await assertActivatableSkills(
+            session.accessor.get(ISessionSkillCatalog),
+            req.body.skills,
+          );
+        }
         await assertPromptSessionMediaRefs(
           req.body.content,
           session.accessor.get(ISessionMediaStore),
@@ -285,6 +338,38 @@ export function registerPromptsRoutes(app: PromptRouteHost, core: Scope): void {
           }
         }
         const parts = contentToCoreParts(resolvedContent);
+        if (req.body.skills !== undefined) {
+          // Bundled skill submission: the engine validates every skill up
+          // front, records one activation event per skill, and enqueues a
+          // single user message (rendered skill blocks first, then the
+          // caller's parts). It owns the prompt-metadata update for the main
+          // agent, so this edge skips its own to avoid a double write.
+          const result = await resolved.skill.promptWithSkills({
+            input: parts,
+            skills: req.body.skills,
+          });
+          enqueued = true;
+          // Queued bundles complete media intake only when their turn pops;
+          // the result shape carries no handle, so the plain path's deferred
+          // cleanup is mirrored through the prompt lifecycle events instead.
+          if (result.state !== 'queued') await preparedMedia?.discard();
+          else deferDiscardUntilPromptSettles(resolved.events, result.prompt_id, () => preparedMedia?.discard());
+          reply.send(
+            okEnvelope(
+              {
+                prompt_id: result.prompt_id,
+                // prompt_id IS the user_message_id — one identity for prompt
+                // and message, same as the plain-prompt path.
+                user_message_id: result.prompt_id,
+                status: result.state,
+                content: projectPromptContentParts(parts),
+                created_at: result.created_at,
+              },
+              req.id,
+            ),
+          );
+          return;
+        }
         await applyPromptMetadataUpdate({
           metadata: session.accessor.get(ISessionMetadata),
           eventService: core.accessor.get(IEventService),
@@ -402,10 +487,16 @@ function projectPromptHandle(handle: PromptHandle) {
   return projectPromptSnapshot(handle);
 }
 
-function projectPromptSnapshot(prompt: PromptQueueSnapshot['pending'][number]) {
+export function projectPromptSnapshot(prompt: PromptQueueSnapshot['pending'][number]) {
   const status = prompt.state === 'running' || prompt.state === 'steered'
     ? 'running'
     : prompt.state === 'blocked' ? 'blocked' : 'queued';
+  const origin = prompt.message.origin;
+  // A bundled prompt stores the rendered skill blocks ahead of the caller's
+  // parts; project the caller's parts only, so the listed content matches the
+  // submit response for the same prompt.
+  const bundled = origin?.kind === 'user' ? (origin.skillActivations?.length ?? 0) : 0;
+  const content = bundled === 0 ? prompt.message.content : prompt.message.content.slice(bundled);
   // The prompt queue holds user prompts only; the shared projection maps each
   // self-contained daemon-ref media part to its `{kind:'session_media'}` wire
   // shape, mirroring the message projection: the internal URL never reaches
@@ -414,11 +505,35 @@ function projectPromptSnapshot(prompt: PromptQueueSnapshot['pending'][number]) {
     prompt_id: prompt.id,
     user_message_id: prompt.userMessageId,
     status,
-    content: projectPromptContentParts(prompt.message.content),
+    content: projectPromptContentParts(content),
     created_at: prompt.createdAt,
   };
 }
 
+/**
+ * Deferred media-staging cleanup for a queued bundled submission: the
+ * bundle's prompt intake only runs when its turn pops (or settles), so the
+ * staging upload is discarded on the matching `prompt.completed` /
+ * `prompt.aborted` lifecycle event rather than eagerly at submit time.
+ * Mirrors the plain path's `launched`/`completion`-raced discard, which the
+ * `promptWithSkills` result shape cannot express.
+ */
+export function deferDiscardUntilPromptSettles(
+  events: IEventService,
+  promptId: string,
+  discard: () => void | Promise<void>,
+): void {
+  const subscription = events.subscribe((event) => {
+    if (
+      (event.type === 'prompt.completed' || event.type === 'prompt.aborted') &&
+      (event as { readonly promptId?: unknown }).promptId === promptId
+    ) {
+      subscription.dispose();
+      void discard();
+    }
+  });
+}
+
 
 
 function sendMappedError(
@@ -459,6 +574,12 @@ function sendMappedError(
       case 'validation.failed':
         reply.send(errEnvelope(ErrorCode.VALIDATION_FAILED, err.message, requestId, err.stack));
         return;
+      case 'skill.not_found':
+        reply.send(errEnvelope(ErrorCode.SKILL_NOT_FOUND, err.message, requestId, err.stack));
+        return;
+      case 'skill.type_unsupported':
+        reply.send(errEnvelope(ErrorCode.SKILL_NOT_ACTIVATABLE, err.message, requestId, err.stack));
+        return;
       case 'auth.provisioning_required':
         reply.send({
           code: ErrorCode.AUTH_PROVISIONING_REQUIRED,