feat(agent): depersonalize the load_skill tool schema for a shared cache prefix (RFC 0001)

docs/guides/agents.md

@@ -282,7 +282,8 @@ boundary for `load_skill`, not just a prompt filter.
 
 Local and project runtimes also expose `load_skill_reference` and
 `execute_skill_script`. Hosted chat reads an advertised reference through
-`load_skill({ skillId, file })` and does not execute skill scripts directly.
+`load_skill({ load: { skillId, file } })` and does not execute skill scripts
+directly.
 
 See [Project structure](./project-structure.md) for `skills/` conventions and
 [Configuration](./configuration.md) for discovery paths.
@@ -291,9 +292,9 @@ See [Project structure](./project-structure.md) for `skills/` conventions and
 
 When an agent uses a skill, the flow is:
 
-1. Call `load_skill({ skillId })` to load the skill instructions and policy.
+1. Call `load_skill({ load: { skillId } })` to load the skill instructions and policy.
 2. Read an advertised reference with `load_skill_reference(...)` on local and
-   project runtimes, or `load_skill({ skillId, file })` in hosted chat.
+   project runtimes, or `load_skill({ load: { skillId, file } })` in hosted chat.
 3. On local and project runtimes, optionally call
    `execute_skill_script(...)` to run scripts from `scripts/`.
 4. Continue with normal tool calls. Loading a skill does not change which

docs/guides/skills.md

@@ -96,12 +96,22 @@ supporting skill tools:
 
 | Tool                   | Availability               | Description                                                |
 | ---------------------- | -------------------------- | ---------------------------------------------------------- |
-| `load_skill`           | Every runtime              | Load a skill's full instructions by ID                     |
+| `load_skill`           | Every runtime              | List authorized IDs or load full instructions by ID        |
 | `load_skill_reference` | Local and project runtimes | Read a file from `references/`, `resources/`, or `assets/` |
 | `execute_skill_script` | Local and project runtimes | Execute a script from a skill (5-minute timeout)           |
 
-Hosted chat reads an advertised reference through
-`load_skill({ skillId, file })`. It does not execute skill scripts directly.
+After loading a skill, hosted chat can read only a reference listed by that
+skill through `load_skill({ load: { skillId, file } })`. It does not execute
+skill scripts directly. Direct tool consumers can continue to use the legacy
+flat input forms.
+
+When the prompt provides a discovery cursor, call
+`load_skill({ inventory: { cursor: <CURSOR> } })`. Otherwise, call
+`load_skill({ inventory: {} })` when the prompt does not show the complete
+authorized skill inventory. The result contains a bounded `skillIds` page. If
+it also contains `nextCursor`, call
+`load_skill({ inventory: { cursor: nextCursor } })` until the response omits
+`nextCursor`. Then call `load_skill({ load: { skillId } })` with a listed ID.
 
 Discovered skills visible to the agent are advertised by default:
 

src/agent/hosted/cloud-runtime-system-messages.test.ts

@@ -1,4 +1,5 @@
 import { assertEquals, assertStringIncludes } from "#veryfront/testing/assert.ts";
+import { it } from "#veryfront/testing/bdd.ts";
 import {
   buildVeryfrontCloudRuntimeInstructions,
   createVeryfrontCloudRuntimeSystemMessages,
@@ -139,3 +140,22 @@ Deno.test("buildVeryfrontCloudRuntimeInstructions adapts hosted preparation inpu
   assertEquals(environmentMessage?.role, "system");
   assertStringIncludes(environmentMessage?.content ?? "", "Runtime facts");
 });
+
+it("buildVeryfrontCloudRuntimeInstructions preserves an authoritative empty skill set", () => {
+  const [message] = buildVeryfrontCloudRuntimeInstructions({
+    agentConfig: createAgent({
+      instructions:
+        "Base\n\n<available_skills>\n- stale: Stale authored skill\n</available_skills>",
+    }),
+    projectId: "project-123",
+    branchId: null,
+    environmentContext: "",
+    instructions: "",
+    skills: [],
+  });
+
+  assertStringIncludes(
+    message?.content ?? "",
+    "<authorized_skill_ids>\n[]\n</authorized_skill_ids>",
+  );
+});

src/agent/hosted/cloud-runtime-system-messages.ts

@@ -43,7 +43,7 @@ export function buildVeryfrontCloudRuntimeInstructions(
   return createVeryfrontCloudRuntimeSystemMessages({
     agent: input.agentConfig,
     instructions: input.instructions || undefined,
-    skills: input.skills.length > 0 ? input.skills : undefined,
+    skills: input.skills,
     projectId: input.projectId,
     branchId: input.branchId,
     environmentContext: input.environmentContext,

src/agent/index.ts

@@ -1362,6 +1362,7 @@ export {
   RUNTIME_LOAD_SKILL_DESCRIPTION,
   type RuntimeLoadSkillBuiltinStore,
   type RuntimeLoadSkillErrorOutput,
+  type RuntimeLoadSkillInventoryOutput,
   type RuntimeLoadSkillReferenceFileOutput,
   type RuntimeLoadSkillToolContext,
   type RuntimeLoadSkillToolInput,

src/agent/runtime/call-context.test.ts

@@ -243,18 +243,118 @@ describe("agent/runtime/call-context", () => {
       assertEquals((messages[0]?.content ?? "").includes("Runtime facts"), false);
     });
 
-    it("skips the skills block when the instructions already carry one", () => {
+    it("keeps authorized skill IDs when instructions already carry a skills block", () => {
       const [message] = buildAgentCallContext({
         instructions:
           "Base\n\n<available_skills>\n- authored: An authored catalog\n</available_skills>",
         skills: createSkills(),
       });
 
-      assertEquals(
-        message?.content,
+      assertStringIncludes(
+        message?.content ?? "",
         "Base\n\n<available_skills>\n- authored: An authored catalog\n</available_skills>",
       );
       assertEquals((message?.content ?? "").includes("Deployment guidance"), false);
+      assertStringIncludes(
+        message?.content ?? "",
+        '<authorized_skill_ids>\n["deploy","review"]\n</authorized_skill_ids>',
+      );
+    });
+
+    it("bounds authorized skill IDs beside an authored skills block", () => {
+      const skills = Array.from(
+        { length: 1_000 },
+        (_, index) => ({
+          id: `skill-${index}-${"x".repeat(240)}`,
+          name: `skill-${index}`,
+          description: `Description ${index}`,
+          instructions: `Instructions ${index}`,
+        }),
+      );
+      const [message] = buildAgentCallContext({
+        instructions:
+          "Base\n\n<available_skills>\n- authored: An authored catalog\n</available_skills>",
+        skills,
+      });
+      const content = message?.content ?? "";
+      const cursorMatch = /Call load_skill\(\{ inventory: \{ cursor: (\d+) \} \}\)/.exec(
+        content,
+      );
+
+      assertEquals(cursorMatch === null, false);
+      assertEquals(Number(cursorMatch?.[1]), content.match(/"skill-/g)?.length);
+      assertEquals(content.length < 21_000, true);
+    });
+
+    it("emits an empty authorized inventory for an authoritative empty skill set", () => {
+      const [message] = buildAgentCallContext({
+        instructions:
+          "Base\n\n<available_skills>\n- stale: An authored catalog\n</available_skills>",
+        skills: [],
+      });
+
+      assertStringIncludes(
+        message?.content ?? "",
+        "<authorized_skill_ids>\n[]\n</authorized_skill_ids>",
+      );
+    });
+
+    it("replaces an earlier generated skill-ID fallback during recomposition", () => {
+      const [first] = buildAgentCallContext({
+        instructions:
+          "Base\n\n<available_skills>\n- authored: An authored catalog\n</available_skills>",
+        skills: createSkills(),
+      });
+      const [second] = buildAgentCallContext({
+        instructions: first?.content ?? "",
+        skills: [{
+          id: "audit",
+          name: "Audit",
+          description: "Audit guidance",
+          instructions: "Audit the change",
+        }],
+      });
+
+      assertEquals((second?.content ?? "").match(/<authorized_skill_ids>/g)?.length, 1);
+      assertStringIncludes(
+        second?.content ?? "",
+        '<authorized_skill_ids>\n["audit"]\n</authorized_skill_ids>',
+      );
+      assertEquals((second?.content ?? "").includes('["deploy"'), false);
+    });
+
+    it("removes an earlier skill-ID discovery cursor during recomposition", () => {
+      const largeCatalog = Array.from(
+        { length: 1_000 },
+        (_, index) => ({
+          id: `skill-${index}-${"x".repeat(240)}`,
+          name: `skill-${index}`,
+          description: `Description ${index}`,
+          instructions: `Instructions ${index}`,
+        }),
+      );
+      const [first] = buildAgentCallContext({
+        instructions:
+          "Base\n\n<available_skills>\n- authored: An authored catalog\n</available_skills>",
+        skills: largeCatalog,
+      });
+      assertStringIncludes(first?.content ?? "", "<authorized_skill_id_discovery>");
+
+      const [second] = buildAgentCallContext({
+        instructions: first?.content ?? "",
+        skills: [{
+          id: "audit",
+          name: "Audit",
+          description: "Audit guidance",
+          instructions: "Audit the change",
+        }],
+      });
+
+      assertEquals((second?.content ?? "").includes("<authorized_skill_id_discovery>"), false);
+      assertStringIncludes(
+        second?.content ?? "",
+        '<authorized_skill_ids>\n["audit"]\n</authorized_skill_ids>',
+      );
     });
 
     it("still emits the skills block when the instructions only name the tag in prose", () => {

src/agent/runtime/call-context.ts

@@ -16,7 +16,8 @@
  * 1. One cached system message holding, in order, the instructions before the
  *    runtime-context marker, `<project_instructions>`, `<project_context>`,
  *    any caller-supplied extra blocks, the instructions after the marker, and
- *    `<available_skills>`.
+ *    `<available_skills>`, or an `<authorized_skill_ids>` fallback
+ *    when the instructions already carry an authored skill catalog.
  * 2. An uncached `<environment_context>` message.
  *
  * Only the instructions are unconditional: each block appears only when the
@@ -31,14 +32,19 @@
 
 import type { ChatSystemMessage } from "#veryfront/chat/types.ts";
 import { createRuntimePromptBlock } from "./prompt-block.ts";
-import { buildRuntimeAvailableSkillsPromptBlock } from "./skill-prompt.ts";
+import {
+  buildRuntimeAuthorizedSkillIdsPromptBlock,
+  buildRuntimeAvailableSkillsPromptBlock,
+} from "./skill-prompt.ts";
 import type { RuntimeSkillDefinition } from "./skill-metadata.ts";
 
 /** Marker authored instructions use to place runtime blocks mid-prompt. */
 export const DEFAULT_RUNTIME_AGENT_CONTEXT_MARKER = "<!-- veryfront-runtime-context -->";
 
 const ENVIRONMENT_CONTEXT_BLOCK_NAME = "environment_context";
 const AVAILABLE_SKILLS_BLOCK_NAME = "available_skills";
+const AUTHORIZED_SKILL_IDS_BLOCK_NAME = "authorized_skill_ids";
+const AUTHORIZED_SKILL_ID_DISCOVERY_BLOCK_NAME = "authorized_skill_id_discovery";
 
 /** Project the call runs against, rendered as the `<project_context>` block. */
 export type AgentCallProjectContext = {
@@ -123,11 +129,37 @@ function hasBlock(instructions: string, blockName: string): boolean {
   return instructions.indexOf(`</${blockName}>`, openIndex) > openIndex;
 }
 
+function removeCompleteBlocks(instructions: string, blockName: string): string {
+  const openTag = `<${blockName}>`;
+  const closeTag = `</${blockName}>`;
+  let result = instructions;
+  let openIndex = result.indexOf(openTag);
+
+  while (openIndex >= 0) {
+    const closeIndex = result.indexOf(closeTag, openIndex + openTag.length);
+    if (closeIndex < 0) {
+      break;
+    }
+    const before = result.slice(0, openIndex).trimEnd();
+    const after = result.slice(closeIndex + closeTag.length).trimStart();
+    result = before.length > 0 && after.length > 0 ? `${before}\n\n${after}` : `${before}${after}`;
+    openIndex = result.indexOf(openTag);
+  }
+
+  return result;
+}
+
 /** Builds the complete system-message set for one provider call. */
 export function buildAgentCallContext(input: BuildAgentCallContextInput): ChatSystemMessage[] {
   const runtimeContextMarker = input.runtimeContextMarker ?? DEFAULT_RUNTIME_AGENT_CONTEXT_MARKER;
+  const sourceInstructions = input.skills === undefined
+    ? input.instructions
+    : removeCompleteBlocks(
+      removeCompleteBlocks(input.instructions, AUTHORIZED_SKILL_IDS_BLOCK_NAME),
+      AUTHORIZED_SKILL_ID_DISCOVERY_BLOCK_NAME,
+    );
   const instructions = splitInstructionsAtMarker({
-    instructions: input.instructions,
+    instructions: sourceInstructions,
     runtimeContextMarker,
   });
 
@@ -151,7 +183,7 @@ export function buildAgentCallContext(input: BuildAgentCallContextInput): ChatSy
       continue;
     }
     const blockName = getBlockName(block);
-    if (blockName !== null && hasBlock(input.instructions, blockName)) {
+    if (blockName !== null && hasBlock(sourceInstructions, blockName)) {
       continue;
     }
     staticParts.push(block);
@@ -161,10 +193,15 @@ export function buildAgentCallContext(input: BuildAgentCallContextInput): ChatSy
     staticParts.push(instructions.after);
   }
 
-  if (input.skills?.length && !hasBlock(input.instructions, AVAILABLE_SKILLS_BLOCK_NAME)) {
-    staticParts.push(
-      buildRuntimeAvailableSkillsPromptBlock(input.skills),
-    );
+  if (input.skills !== undefined) {
+    const hasAuthoredSkillCatalog = hasBlock(sourceInstructions, AVAILABLE_SKILLS_BLOCK_NAME);
+    if (input.skills.length > 0 || hasAuthoredSkillCatalog) {
+      staticParts.push(
+        hasAuthoredSkillCatalog
+          ? buildRuntimeAuthorizedSkillIdsPromptBlock(input.skills)
+          : buildRuntimeAvailableSkillsPromptBlock(input.skills),
+      );
+    }
   }
 
   const messages: ChatSystemMessage[] = [
@@ -177,7 +214,7 @@ export function buildAgentCallContext(input: BuildAgentCallContextInput): ChatSy
     },
   ];
 
-  if (input.environmentContext && !hasBlock(input.instructions, ENVIRONMENT_CONTEXT_BLOCK_NAME)) {
+  if (input.environmentContext && !hasBlock(sourceInstructions, ENVIRONMENT_CONTEXT_BLOCK_NAME)) {
     messages.push({
       role: "system",
       content: createRuntimePromptBlock({