@vellumai/assistant 0.12.3-dev.202609221821.7bf89b6 → 0.12.3-dev.202609222113.8a21e65

package/openapi.yaml

@@ -26971,7 +26971,12 @@ paths:
                   assistantId:
                     type: string
                   hasAssistantApiKey:
-                    type: boolean
+                    anyOf:
+                      - type: boolean
+                      - type: "null"
+                    description:
+                      Whether a managed assistant API key is stored. Null when the credential store could not be read, which is
+                      not evidence that no key is stored.
                   hasWebhookSecret:
                     type: boolean
                   clientInstallationId:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.3-dev.202609221821.7bf89b6",
+  "version": "0.12.3-dev.202609222113.8a21e65",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/channel-readiness-discord.test.ts

@@ -4,8 +4,16 @@ import { credentialKey } from "../security/credential-key.js";
 
 let mockSecureKeys: Record<string, string>;
 
+// Spread the real module: mocks are shared across files in a combined run,
+// and a wholesale replacement drops the exports peer modules import.
+const actualSecureKeys = await import("../security/secure-keys.js");
 mock.module("../security/secure-keys.js", () => ({
+  ...actualSecureKeys,
   getSecureKeyAsync: async (key: string) => mockSecureKeys[key] ?? null,
+  getSecureKeyResultAsync: async (key: string) => ({
+    value: mockSecureKeys[key] ?? undefined,
+    unreachable: false,
+  }),
   setSecureKeyAsync: async (key: string, value: string) => {
     mockSecureKeys[key] = value;
     return true;

package/src/__tests__/channel-readiness-slack-remote.test.ts

@@ -5,8 +5,16 @@ import { setConfig } from "./helpers/set-config.js";
 
 let mockSecureKeys: Record<string, string>;
 
+// Spread the real module: mocks are shared across files in a combined run,
+// and a wholesale replacement drops the exports peer modules import.
+const actualSecureKeys = await import("../security/secure-keys.js");
 mock.module("../security/secure-keys.js", () => ({
+  ...actualSecureKeys,
   getSecureKeyAsync: async (key: string) => mockSecureKeys[key] ?? null,
+  getSecureKeyResultAsync: async (key: string) => ({
+    value: mockSecureKeys[key] ?? undefined,
+    unreachable: false,
+  }),
   setSecureKeyAsync: async (key: string, value: string) => {
     mockSecureKeys[key] = value;
     return true;

package/src/__tests__/conversation-pairing.test.ts

@@ -996,6 +996,12 @@ describe("pairDeliveryWithConversation", () => {
     expect(createConversationMock).not.toHaveBeenCalled();
     expect(addMessageMock).toHaveBeenCalledTimes(1);
     expect(messagesInvalidated).toContain("conv-foreground");
+    // The transcript is this notification's only home, so a chat marked Done
+    // comes back for it.
+    const options = addMessageMock.mock.calls[0]![3] as {
+      skipResurface?: boolean;
+    };
+    expect(options.skipResurface).toBe(false);
   });
 
   test("appended notification body skips indexing", async () => {
@@ -1017,8 +1023,12 @@ describe("pairDeliveryWithConversation", () => {
 
     const options = addMessageMock.mock.calls[0]![3] as {
       skipIndexing?: boolean;
+      skipResurface?: boolean;
     };
     expect(options.skipIndexing).toBe(true);
+    // The bell carries this one (async-background), so the append is
+    // bookkeeping and never resurfaces a chat the user marked Done.
+    expect(options.skipResurface).toBe(true);
   });
 
   test("passive vellum signal appends regardless of the producing conversation's source", async () => {

package/src/__tests__/job-handler-registration-guard.test.ts

@@ -35,6 +35,7 @@ const MEMORY_JOB_TYPES = [
   "memory_retrospective",
   "memory_retrospective_sweep",
   "skill_card_insert",
+  "skill_update_receipt",
   "pkb_filing",
   "pkb_compaction",
 ].sort();

package/src/__tests__/openai-responses-prompt-cache.test.ts

@@ -446,7 +446,7 @@ describe("OpenAIResponsesProvider explicit prompt caching (GPT-5.6+)", () => {
     expect(JSON.stringify(messages)).not.toContain("prompt_cache_breakpoint");
   });
 
-  test("catalog flags GPT-5.6 and GPT-6 Astra direct-openai rows", () => {
+  test("catalog flags GPT-5.6 and GPT-6 direct-openai rows", () => {
     const openai = PROVIDER_CATALOG.find((p) => p.id === "openai");
     const flagged = (openai?.models ?? [])
       .filter((m) => m.supportsPromptCacheBreakpoints)
@@ -457,6 +457,8 @@ describe("OpenAIResponsesProvider explicit prompt caching (GPT-5.6+)", () => {
       "gpt-5.6-sol",
       "gpt-5.6-terra",
       "gpt-6-astra",
+      "gpt-6-luna",
+      "gpt-6-sol",
     ]);
   });
 });

package/src/__tests__/platform-callback-registration.test.ts

@@ -11,6 +11,7 @@ let mockVelayWebhooksEnabled = false;
 let mockPlatformBaseUrl = "";
 let mockPlatformAssistantId = "";
 let mockSecureKeys: Record<string, string> = {};
+let mockSecureKeysUnreachable = false;
 let mockConfig: { ingress?: { publicBaseUrl?: string; enabled?: boolean } } =
   {};
 
@@ -65,7 +66,12 @@ mock.module("../ipc/gateway-client.js", () => ({
 const actualSecureKeys = await import("../security/secure-keys.js");
 mock.module("../security/secure-keys.js", () => ({
   ...actualSecureKeys,
-  getSecureKeyAsync: async (key: string) => mockSecureKeys[key] ?? undefined,
+  getSecureKeyAsync: async (key: string) =>
+    mockSecureKeysUnreachable ? undefined : (mockSecureKeys[key] ?? undefined),
+  getSecureKeyResultAsync: async (key: string) =>
+    mockSecureKeysUnreachable
+      ? { value: undefined, unreachable: true }
+      : { value: mockSecureKeys[key] ?? undefined, unreachable: false },
 }));
 
 const actualLoader = await import("../config/loader.js");
@@ -92,6 +98,7 @@ describe("platform callback registration", () => {
     mockPlatformBaseUrl = "";
     mockPlatformAssistantId = "";
     mockSecureKeys = {};
+    mockSecureKeysUnreachable = false;
     mockConfig = {};
     setIngressPublicBaseUrl(undefined);
     delete process.env.ASSISTANT_API_KEY;
@@ -156,6 +163,43 @@ describe("platform callback registration", () => {
     expect(context.authHeader).toBe("Api-Key env-key");
   });
 
+  test("reports the key as missing when the store answers and holds none", async () => {
+    mockPlatformBaseUrl = "https://platform.example.com";
+    mockPlatformAssistantId = "44444444-5555-4666-8777-888888888888";
+
+    const context = await resolvePlatformCallbackRegistrationContext();
+
+    expect(context.hasAssistantApiKey).toBe(false);
+    expect(context.authHeader).toBeNull();
+    expect(context.enabled).toBe(false);
+  });
+
+  test("reports the key state as unknown when the store did not answer", async () => {
+    // A client that provisions a key when it sees none must not be told
+    // "none" by a daemon whose store did not answer.
+    mockSecureKeysUnreachable = true;
+    mockPlatformBaseUrl = "https://platform.example.com";
+    mockPlatformAssistantId = "44444444-5555-4666-8777-888888888888";
+
+    const context = await resolvePlatformCallbackRegistrationContext();
+
+    expect(context.hasAssistantApiKey).toBeNull();
+    expect(context.authHeader).toBeNull();
+    expect(context.enabled).toBe(false);
+  });
+
+  test("an environment key counts as present even when the store did not answer", async () => {
+    mockSecureKeysUnreachable = true;
+    process.env.ASSISTANT_API_KEY = "env-key";
+    mockPlatformBaseUrl = "https://platform.example.com";
+    mockPlatformAssistantId = "44444444-5555-4666-8777-888888888888";
+
+    const context = await resolvePlatformCallbackRegistrationContext();
+
+    expect(context.hasAssistantApiKey).toBe(true);
+    expect(context.authHeader).toBe("Api-Key env-key");
+  });
+
   test("registerCallbackRoute falls back to assistant API key auth", async () => {
     mockSecureKeys[credentialKey("vellum", "platform_base_url")] =
       "https://platform.example.com";
@@ -402,6 +446,7 @@ describe("resolveCallbackUrl resolution order", () => {
     mockPlatformBaseUrl = "";
     mockPlatformAssistantId = "";
     mockSecureKeys = {};
+    mockSecureKeysUnreachable = false;
     mockConfig = {};
     setIngressPublicBaseUrl(undefined);
     delete process.env.ASSISTANT_API_KEY;

package/src/__tests__/plugin-import-boundary-guard.test.ts

@@ -196,6 +196,9 @@ const BASELINE: Record<string, readonly string[]> = {
     "../../../daemon/trust-context.js",
     "../../../home/job-handlers/conversation-starters.js",
     "../../../media/job-handlers/media-processing.js",
+    // The skill-update receipt job announces a burst through the
+    // notification pipeline's single entry point. No plugin-api equivalent.
+    "../../../notifications/emit-signal.js",
     "../../../permissions/types.js",
     "../../../persistence/auto-analysis-constants.js",
     "../../../persistence/checkpoints.js",

package/src/__tests__/pricing.test.ts

@@ -135,6 +135,39 @@ describe("resolvePricing", () => {
       expect(result.estimatedCostUsd).toBeCloseTo(0.5 + 0.625 + 0.05, 10);
     });
 
+    test("bills GPT-6 Sol at published short-context rates", () => {
+      const result = resolvePricingForUsage("openai", "gpt-6-sol", {
+        directInputTokens: 50_000,
+        outputTokens: 50_000,
+        cacheCreationInputTokens: 50_000,
+        cacheReadInputTokens: 50_000,
+        anthropicCacheCreation: null,
+      });
+
+      expect(result.pricingStatus).toBe("priced");
+      // 0.05M x $2 direct + 0.05M x $2.5 write + 0.05M x $0.2 read
+      // + 0.05M x $10 output.
+      expect(result.estimatedCostUsd).toBeCloseTo(0.1 + 0.125 + 0.01 + 0.5, 10);
+    });
+
+    test("bills GPT-6 Luna at the long-context tier above 272k", () => {
+      const result = resolvePricingForUsage("openai", "gpt-6-luna", {
+        directInputTokens: 500_000,
+        outputTokens: 1_000_000,
+        cacheCreationInputTokens: 500_000,
+        cacheReadInputTokens: 1_000_000,
+        anthropicCacheCreation: null,
+      });
+
+      expect(result.pricingStatus).toBe("priced");
+      // Tier rates: 0.5M x $0.2 direct + 0.5M x $0.25 write + 1M x $0.02 read
+      // + 1M x $0.75 output.
+      expect(result.estimatedCostUsd).toBeCloseTo(
+        0.1 + 0.125 + 0.02 + 0.75,
+        10,
+      );
+    });
+
     test("bills GPT-6 Astra at the long-context tier above 272k", () => {
       const result = resolvePricingForUsage("openai", "gpt-6-astra", {
         directInputTokens: 500_000,

package/src/__tests__/scaffold-managed-skill-tool.test.ts

@@ -32,25 +32,24 @@ mock.module("../daemon/skill-memory-refresh.js", () => ({
   refreshSkillCapabilityMemories: mockRefreshSkillCapabilityMemories,
 }));
 
-// Background skill updates route through the notification pipeline; record
-// the signals rather than standing up delivery.
-let emittedSignals: Array<{
-  sourceEventName: string;
-  sourceContextId: string;
-  dedupeKey?: string;
-  contextPayload?: Record<string, unknown>;
-}> = [];
-mock.module("../notifications/emit-signal.js", () => ({
-  emitNotificationSignal: async (params: {
-    sourceEventName: string;
-    sourceContextId: string;
-    dedupeKey?: string;
-    contextPayload?: Record<string, unknown>;
-  }) => {
-    emittedSignals.push(params);
-    return { signalId: "test-signal" };
-  },
-}));
+// Receipt recorder: the executor's one side effect for a background
+// overwrite, captured at the job module's boundary so the tests read what
+// was recorded rather than standing up the memory job queue.
+import type * as ReceiptJob from "../plugins/defaults/memory/skill-update-receipt-job.js";
+
+let recordedUpdates: Parameters<typeof ReceiptJob.recordSkillUpdate>[0][] = [];
+let recordUpdateFails = false;
+mock.module(
+  "../plugins/defaults/memory/skill-update-receipt-job.js",
+  (): Partial<typeof ReceiptJob> => ({
+    recordSkillUpdate: (input) => {
+      recordedUpdates.push(input);
+      if (recordUpdateFails) {
+        throw new Error("memory database unavailable");
+      }
+    },
+  }),
+);
 
 // Skill-card enqueue recorder. Snapshot + override (rather than a full module
 // replacement) because other modules in this import graph (e.g. the managed
@@ -152,7 +151,7 @@ beforeEach(() => {
   skillCardJobUpserts = [];
   skillCardUpsertThrows = false;
   watchdogEvents.length = 0;
-  emittedSignals = [];
+  recordedUpdates = [];
 });
 
 afterEach(() => {
@@ -1771,7 +1770,8 @@ describe("background skill update notification", () => {
     });
     watchdogEvents.length = 0;
     skillCardJobUpserts = [];
-    emittedSignals = [];
+    recordedUpdates = [];
+    recordUpdateFails = false;
   }
 
   const lineage = () => ({
@@ -1781,9 +1781,73 @@ describe("background skill update notification", () => {
         : null,
   });
 
-  test("a background overwrite of an existing skill notifies, keyed to the source conversation", async () => {
+  test("a background overwrite of an existing skill records a receipt entry keyed to the tool call", async () => {
     await seedAssistantSkill("weekly-export", "Old body.");
 
+    const result = await executeScaffoldManagedSkill(
+      {
+        skill_id: "weekly-export",
+        name: "Weekly Report Export",
+        description: "export the weekly usage report",
+        body_markdown: "1. Refined steps.",
+        activation_hints: HINTS,
+        overwrite: true,
+        change_summary: "Refined the steps.",
+      },
+      makeRetrospectiveContext({
+        conversationId: "retro-run-conv",
+        toolUseId: "toolu_1",
+      }),
+      lineage(),
+    );
+
+    expect(result.isError).toBe(false);
+    // Nothing is announced here: the entry joins the pending receipt job,
+    // which announces the burst once it has settled.
+    expect(recordedUpdates).toEqual([
+      {
+        // The producing tool call, so a re-executed call records nothing new.
+        entryId: "retro-run-conv:toolu_1",
+        skillId: "weekly-export",
+        name: "Weekly Report Export",
+        changeSummary: "Refined the steps.",
+        runConversationId: "retro-run-conv",
+        // The receipt's link for this entry resolves through this id, so it
+        // must be the conversation the work came from, not the hidden fork.
+        sourceConversationId: "source-conv",
+      },
+    ]);
+  });
+
+  test("an entry without a tool call id gets a fresh key, so a second rewrite of the same skill is still recorded", async () => {
+    await seedAssistantSkill("weekly-export", "Old body.");
+
+    for (const body of ["1. Refined steps.", "1. Refined again."]) {
+      await executeScaffoldManagedSkill(
+        {
+          skill_id: "weekly-export",
+          name: "Weekly Report Export",
+          description: "export the weekly usage report",
+          body_markdown: body,
+          activation_hints: HINTS,
+          overwrite: true,
+          change_summary: `Refined: ${body}`,
+        },
+        makeRetrospectiveContext({ conversationId: "retro-run-conv" }),
+      );
+    }
+
+    expect(recordedUpdates).toHaveLength(2);
+    const [first, second] = recordedUpdates;
+    expect(first?.entryId.startsWith("retro-run-conv:")).toBe(true);
+    expect(second?.entryId.startsWith("retro-run-conv:")).toBe(true);
+    expect(first?.entryId).not.toBe(second?.entryId);
+  });
+
+  test("a receipt that cannot be recorded is logged and counted, and the skill write stands", async () => {
+    await seedAssistantSkill("weekly-export", "Old body.");
+    recordUpdateFails = true;
+
     const result = await executeScaffoldManagedSkill(
       {
         skill_id: "weekly-export",
@@ -1799,29 +1863,20 @@ describe("background skill update notification", () => {
     );
 
     expect(result.isError).toBe(false);
-    expect(emittedSignals).toHaveLength(1);
-    const signal = emittedSignals[0]!;
-    expect(signal.sourceEventName).toBe("activity.complete");
-    // The feed item's "Go to Convo" target resolves through this id, so it
-    // must be the conversation the work came from, not the hidden fork.
-    expect(signal.sourceContextId).toBe("source-conv");
-    expect(signal.contextPayload?.skillId).toBe("weekly-export");
-    expect(signal.contextPayload?.summary).toBe("Refined the steps.");
-    // The home feed falls back to `title`/`body` when no channel copy was
-    // rendered, which is the intended quiet shape for this signal. Without
-    // them a suppressed delivery would leave the feed item unwritten.
-    // Named so the row is scannable in a feed several entries deep.
-    expect(signal.contextPayload?.title).toBe(
-      "Skill updated: Weekly Report Export",
-    );
-    expect(signal.contextPayload?.body).toBe("Refined the steps.");
-    // Deduped per skill per day so repeated refinements cannot flood the feed.
-    expect(signal.dedupeKey).toBe(
-      `skill-updated:weekly-export:${new Date().toISOString().slice(0, 10)}`,
-    );
-  });
-
-  test("the notice body is the pass's change_summary, so the feed says what changed", async () => {
+    expect(
+      readFileSync(
+        join(TEST_DIR, "skills", "weekly-export", "SKILL.md"),
+        "utf-8",
+      ),
+    ).toContain("Refined steps.");
+    expect(watchdogEvents).toContainEqual(
+      expect.objectContaining({
+        checkName: "skill_update_receipt_record_failed",
+      }),
+    );
+  });
+
+  test("the entry body is the pass's change_summary, so the receipt says what changed", async () => {
     await seedAssistantSkill("weekly-export", "Old body.");
 
     const result = await executeScaffoldManagedSkill(
@@ -1840,14 +1895,9 @@ describe("background skill update notification", () => {
     );
 
     expect(result.isError).toBe(false);
-    expect(emittedSignals).toHaveLength(1);
-    const payload = emittedSignals[0]!.contextPayload;
-    // The title still names the skill; the body is the change itself.
-    expect(payload?.title).toBe("Skill updated: Weekly Report Export");
-    expect(payload?.body).toBe(
+    expect(recordedUpdates[0]?.changeSummary).toBe(
       "Added the retry after an expired session and the export endpoint that held steady.",
     );
-    expect(payload?.summary).toBe(payload?.body);
   });
 
   test("a background overwrite without a change_summary is refused before the write", async () => {
@@ -1881,7 +1931,7 @@ describe("background skill update notification", () => {
         'Error: change_summary is required when updating an existing skill: pass one or two short sentences (under 200 characters) for the person who reads the "Skill updated" notice, naming what you changed and what in the trace prompted it (for example "Added the retry after an expired session and the export endpoint that held steady.").',
       );
       expect(readFileSync(skillFile, "utf-8")).toBe(before);
-      expect(emittedSignals).toHaveLength(0);
+      expect(recordedUpdates).toHaveLength(0);
     }
   });
 
@@ -1905,7 +1955,7 @@ describe("background skill update notification", () => {
     expect(result.isError).toBe(true);
     expect(result.content).toContain("Set overwrite=true to replace it.");
     expect(result.content).not.toContain("change_summary");
-    expect(emittedSignals).toHaveLength(0);
+    expect(recordedUpdates).toHaveLength(0);
   });
 
   test("the ownership backstop speaks before the change_summary requirement", async () => {
@@ -1937,7 +1987,7 @@ describe("background skill update notification", () => {
     expect(result.content).toContain("not verifiably assistant-authored");
   });
 
-  test("a user-directed overwrite needs no change_summary: it never notifies", async () => {
+  test("a user-directed overwrite needs no change_summary: it records no entry", async () => {
     await executeScaffoldManagedSkill(
       {
         skill_id: "user-skill",
@@ -1964,7 +2014,7 @@ describe("background skill update notification", () => {
     expect(result.isError).toBe(false);
   });
 
-  test("change_summary is sanitized like any other notification body", async () => {
+  test("change_summary is sanitized like any notification body", async () => {
     await seedAssistantSkill("weekly-export", "Old body.");
 
     await executeScaffoldManagedSkill(
@@ -1981,7 +2031,7 @@ describe("background skill update notification", () => {
       lineage(),
     );
 
-    const body = String(emittedSignals[0]!.contextPayload?.body);
+    const body = String(recordedUpdates[0]?.changeSummary);
     // Control characters go, horizontal whitespace collapses, blank-line runs
     // collapse to one paragraph break, and the whole thing is clamped to the
     // shared notification preview budget.
@@ -2012,7 +2062,7 @@ describe("background skill update notification", () => {
 
     expect(result.isError).toBe(true);
     expect(result.content).toBe("Error: change_summary must be a string");
-    expect(emittedSignals).toHaveLength(0);
+    expect(recordedUpdates).toHaveLength(0);
   });
 
   test("the registered tool's schema declares change_summary as an optional string", () => {
@@ -2044,7 +2094,7 @@ describe("background skill update notification", () => {
     expect(result.ok).toBe(true);
   });
 
-  test("it falls back to the run conversation when fork lineage does not resolve", async () => {
+  test("an entry whose fork lineage does not resolve carries no source, never the run", async () => {
     await seedAssistantSkill("weekly-export", "Old body.");
 
     await executeScaffoldManagedSkill(
@@ -2061,10 +2111,10 @@ describe("background skill update notification", () => {
       { getConversation: () => null },
     );
 
-    // Still a real conversation id, so the deep link resolves rather than
-    // falling through to an unrelated target.
-    expect(emittedSignals).toHaveLength(1);
-    expect(emittedSignals[0]!.sourceContextId).toBe("retro-run-conv");
+    // The run is an ephemeral fork; naming it as the source would have the
+    // receipt job drop the entry once the fork is garbage collected.
+    expect(recordedUpdates).toHaveLength(1);
+    expect(recordedUpdates[0]).not.toHaveProperty("sourceConversationId");
   });
 
   test("a background CREATE gets the skill card instead, with no duplicate signal", async () => {
@@ -2082,10 +2132,10 @@ describe("background skill update notification", () => {
 
     expect(result.isError).toBe(false);
     expect(skillCardJobUpserts).toHaveLength(1);
-    expect(emittedSignals).toHaveLength(0);
+    expect(recordedUpdates).toHaveLength(0);
   });
 
-  test("a user-directed overwrite does not notify: it is not unattended work", async () => {
+  test("a user-directed overwrite records no receipt entry: it is not unattended work", async () => {
     await executeScaffoldManagedSkill(
       {
         skill_id: "user-skill",
@@ -2096,7 +2146,7 @@ describe("background skill update notification", () => {
       },
       makeContext(),
     );
-    emittedSignals = [];
+    recordedUpdates = [];
 
     await executeScaffoldManagedSkill(
       {
@@ -2113,6 +2163,6 @@ describe("background skill update notification", () => {
     expect(
       readFileSync(join(TEST_DIR, "skills", "user-skill", "SKILL.md"), "utf-8"),
     ).toContain("V2.");
-    expect(emittedSignals).toHaveLength(0);
+    expect(recordedUpdates).toHaveLength(0);
   });
 });

package/src/__tests__/skill-load-tool.test.ts

@@ -1,4 +1,4 @@
-import { mkdirSync, symlinkSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { beforeEach, describe, expect, mock, test } from "bun:test";
 
@@ -781,16 +781,48 @@ describe("skill_load tool", () => {
     expect(result.content).toContain("Deploy the application to production");
     expect(result.content).toContain("Rollback to previous version");
 
-    // Should list parameters with types and required/optional markers
-    expect(result.content).toContain(
-      "- environment (string, required): Target environment",
+    const schemas = [
+      ...result.content.matchAll(/```json\n([\s\S]*?)\n```/g),
+    ].map((match) => JSON.parse(match[1]));
+    expect(schemas[0].required).toEqual(["environment"]);
+    expect(schemas[0].properties.environment).toEqual({
+      type: "string",
+      description: "Target environment",
+    });
+    expect(schemas[0].properties.force.type).toBe("boolean");
+    expect(schemas[1].required).toEqual(["version"]);
+  });
+
+  test("discloses the complete annotation mark schema before execution", async () => {
+    const manifest = JSON.parse(
+      readFileSync(
+        join(
+          import.meta.dir,
+          "../config/bundled-skills/screen-annotation/TOOLS.json",
+        ),
+        "utf-8",
+      ),
     );
-    expect(result.content).toContain(
-      "- force (boolean, optional): Force deploy even if checks fail",
+    writeSkill(
+      "annotation-schema",
+      "Annotation Schema",
+      "Point at a control",
+      "Name the control.",
     );
-    expect(result.content).toContain(
-      "- version (string, required): Version to rollback to",
+    writeToolsJson("annotation-schema", manifest.tools);
+
+    const result = await executeSkillLoad(
+      { skill: "annotation-schema" },
+      "macos",
     );
+    expect(result.isError).toBe(false);
+    const schemaMatch = result.content.match(/```json\n([\s\S]*?)\n```/);
+    expect(schemaMatch).not.toBeNull();
+    const schema = JSON.parse(schemaMatch![1]);
+    expect(schema).toEqual(manifest.tools[0].input_schema);
+    expect(schema.properties.marks.items.oneOf).toHaveLength(2);
+    expect(schema.properties.marks.items.properties.target.minLength).toBe(1);
+    expect(schema.properties.marks.items.properties.caption.maxLength).toBe(80);
   });
 
   test("skill without TOOLS.json does not include tool schemas section", async () => {
@@ -862,9 +894,8 @@ describe("skill_load tool", () => {
     // The child skill's tool schemas should appear (#### level under ### Tools from …)
     expect(result.content).toContain("#### child_action");
     expect(result.content).toContain("A child tool action");
-    expect(result.content).toContain(
-      "- target (string, required): Action target",
-    );
+    const schemaMatch = result.content.match(/```json\n([\s\S]*?)\n```/);
+    expect(JSON.parse(schemaMatch![1]).required).toEqual(["target"]);
     expect(result.content).toContain(
       "Use `skill_execute` to call these tools.",
     );