From f60ee28455277253bf54da291c644e4be674c651 Mon Sep 17 00:00:00 2001 From: "lia-by-librechat[bot]" <328778573+lia-by-librechat[bot]@users.noreply.github.com> Date: Sun, 20 Sep 2026 05:24:57 -0400 Subject: [PATCH] =?UTF-8?q?=F0=9F=90=A3=20feat:=20Invoke=20Newly=20Authore?= =?UTF-8?q?d=20Skills=20In=20the=20Same=20Run=20(#16036)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 🐣 feat: Invoke Newly Authored Skills In the Same Run * test: Pin the SDK skill tool text the authoring variant rewrites * fix: Replace a stale skill definition instead of suppressing the duplicate * fix: Pin Skill Invocation to the Doc Authored In the Run --------- Co-authored-by: Lia --- .../src/agents/__tests__/initialize.test.ts | 6 +- .../api/src/agents/__tests__/skills.test.ts | 149 +++++- packages/api/src/agents/handlers.spec.ts | 431 ++++++++++++++++++ packages/api/src/agents/handlers.ts | 114 ++++- packages/api/src/agents/initialize.ts | 11 +- packages/api/src/agents/skills.ts | 64 ++- packages/api/src/agents/tools.spec.ts | 215 +++++++++ packages/api/src/agents/tools.ts | 119 ++++- 8 files changed, 1077 insertions(+), 32 deletions(-) diff --git a/packages/api/src/agents/__tests__/initialize.test.ts b/packages/api/src/agents/__tests__/initialize.test.ts index 36fcc14add..84271fad94 100644 --- a/packages/api/src/agents/__tests__/initialize.test.ts +++ b/packages/api/src/agents/__tests__/initialize.test.ts @@ -2522,10 +2522,12 @@ describe('initializeAgent — skill `allowed-tools` union (Phase 6)', () => { /* Two attempts (initial + retry), both undefined. Registry-backed tools fall away, but read/create/edit_file are registered by the initializer - so skill authoring still works. */ + so skill authoring still works — and `skill` comes with them, so a + skill authored in this run can still be invoked despite the empty + catalog. */ expect(loadTools).toHaveBeenCalledTimes(2); const definedNames = result.toolDefinitions?.map((d) => d.name) ?? []; - expect(definedNames).toEqual(['read_file', 'create_file', 'edit_file']); + expect(definedNames).toEqual(['read_file', 'create_file', 'edit_file', 'skill']); }); it('propagates the error when loadTools fails AND there are no skill-added extras to drop', async () => { diff --git a/packages/api/src/agents/__tests__/skills.test.ts b/packages/api/src/agents/__tests__/skills.test.ts index ceda9e3e0f..25c761a28a 100644 --- a/packages/api/src/agents/__tests__/skills.test.ts +++ b/packages/api/src/agents/__tests__/skills.test.ts @@ -14,7 +14,23 @@ jest.mock('@librechat/agents', () => ({ .Constants, SKILL_TOOL: 'skill', }, - SkillToolDefinition: { name: 'skill', description: 'skill tool', parameters: {} }, + SkillToolDefinition: { + name: 'skill', + description: `skill tool + +CONSTRAINTS: +- Skill names come from the catalog only. Do not guess names.`, + parameters: { + type: 'object', + properties: { + skillName: { + type: 'string', + description: 'Must match a name from the "Available Skills" section.', + }, + }, + required: ['skillName'], + }, + }, ReadFileToolDefinition: { name: 'read_file', description: 'read file', @@ -1373,6 +1389,137 @@ describe('injectSkillCatalog', () => { catalog-visible skill. */ expect(names).toContain('skill'); }); + + it('registers the skill tool with an empty catalog when the run can author skills', async () => { + /* A model that can write `skills/{skillName}/SKILL.md` needs the `skill` + tool bound at init: definitions bind once per run, so a run that only + learned about the skill after creating it could never invoke it. */ + const listSkillsByAccess = jest.fn(); + const agent = makeAgent(); + const result = await injectSkillCatalog( + baseParams({ + agent, + accessibleSkillIds: [], + listSkillsByAccess, + skillAuthoringAvailable: true, + }), + ); + + const definedNames = (result.toolDefinitions ?? []).map((d) => d.name); + expect(definedNames).toContain('skill'); + expect(result.toolNames).toContain('skill'); + expect(result.skillCount).toBe(0); + expect(result.activeSkillIds).toEqual([]); + expect(agent.additional_instructions).toBeUndefined(); + expect(listSkillsByAccess).not.toHaveBeenCalled(); + }); + + it('omits the skill tool with an empty catalog when the run cannot author skills', async () => { + const result = await injectSkillCatalog( + baseParams({ accessibleSkillIds: [], listSkillsByAccess: jest.fn() }), + ); + + expect((result.toolDefinitions ?? []).map((d) => d.name)).not.toContain('skill'); + expect(result.toolNames).toEqual([]); + }); + + it('registers the skill tool for an authoring run whose only skill is model-disabled', async () => { + const ownedHidden: PageSkill = { + ...makeSkill('owned-hidden-authoring', userObjectId), + disableModelInvocation: true, + }; + const listSkillsByAccess = buildPager([[ownedHidden]]); + const result = await injectSkillCatalog( + baseParams({ listSkillsByAccess, skillAuthoringAvailable: true }), + ); + + const definedNames = (result.toolDefinitions ?? []).map((d) => d.name); + expect(definedNames).toContain('skill'); + expect(definedNames).toContain('read_file'); + expect(result.skillCount).toBe(0); + expect(result.activeSkillIds.map((id) => id.toString())).toEqual([ownedHidden._id.toString()]); + }); + + it('advertises authored skills only on authoring runs', async () => { + const owned = makeSkill('owned-skill', userObjectId); + const authoring = await injectSkillCatalog( + baseParams({ + listSkillsByAccess: buildPager([[owned]]), + skillAuthoringAvailable: true, + }), + ); + const catalogOnly = await injectSkillCatalog( + baseParams({ listSkillsByAccess: buildPager([[owned]]) }), + ); + + const authoringDef = (authoring.toolDefinitions ?? []).find((d) => d.name === 'skill'); + const catalogOnlyDef = (catalogOnly.toolDefinitions ?? []).find((d) => d.name === 'skill'); + expect(authoringDef?.description).toContain('a skill you created in this conversation'); + expect(catalogOnlyDef?.description).toContain('Skill names come from the catalog only'); + }); + + it('replaces an already-registered skill definition instead of leaving it stale', async () => { + /** + * Counting occurrences is not enough: a surviving catalog-only definition + * tells an authoring run's model that a name it just created is invalid, + * which is the failure this registration exists to prevent. Assert the + * definition that survives, and assert the registry the host handler + * resolves agrees with the array the model reads. + */ + const owned = makeSkill('owned-skill', userObjectId); + type ToolRegistryArg = NonNullable[0]['toolRegistry']>; + type ToolDef = Parameters[1]; + const preSkill: ToolDef = { + name: 'skill', + description: 'pre-registered catalog-only definition', + parameters: { type: 'object', properties: {} }, + }; + const preRegistry = new Map() as unknown as ToolRegistryArg; + preRegistry.set('skill', preSkill); + + const result = await injectSkillCatalog( + baseParams({ + listSkillsByAccess: buildPager([[owned]]), + skillAuthoringAvailable: true, + toolRegistry: preRegistry, + toolDefinitions: [preSkill], + }), + ); + + const skillDefs = (result.toolDefinitions ?? []).filter((d) => d.name === 'skill'); + expect(skillDefs).toHaveLength(1); + expect(skillDefs[0].description).not.toBe(preSkill.description); + expect(skillDefs[0].description).toContain('a skill you created in this conversation'); + expect((preRegistry as unknown as Map).get('skill')).toBe(skillDefs[0]); + }); + + it('keeps the non-authoring variant live when it replaces a stale definition', async () => { + /* Same replacement on a run that cannot author: the model must end up with + the SDK definition, never a leftover from an earlier registration. */ + const owned = makeSkill('owned-skill', userObjectId); + type ToolRegistryArg = NonNullable[0]['toolRegistry']>; + type ToolDef = Parameters[1]; + const preSkill: ToolDef = { + name: 'skill', + description: 'stale definition from an earlier registration', + parameters: { type: 'object', properties: {} }, + }; + const preRegistry = new Map() as unknown as ToolRegistryArg; + preRegistry.set('skill', preSkill); + + const result = await injectSkillCatalog( + baseParams({ + listSkillsByAccess: buildPager([[owned]]), + toolRegistry: preRegistry, + toolDefinitions: [preSkill], + }), + ); + + const skillDefs = (result.toolDefinitions ?? []).filter((d) => d.name === 'skill'); + expect(skillDefs).toHaveLength(1); + expect(skillDefs[0].description).toContain('Skill names come from the catalog only'); + expect((preRegistry as unknown as Map).get('skill')).toBe(skillDefs[0]); + }); }); describe('buildSkillPrimeMessage', () => { diff --git a/packages/api/src/agents/handlers.spec.ts b/packages/api/src/agents/handlers.spec.ts index bf71ed678c..53927c17ea 100644 --- a/packages/api/src/agents/handlers.spec.ts +++ b/packages/api/src/agents/handlers.spec.ts @@ -2956,6 +2956,437 @@ describe('createToolExecuteHandler', () => { expect(deleteSkill).toHaveBeenCalledTimes(2); }); + it('invokes a skill created earlier in the same run, starting from an empty catalog', async () => { + /** + * The run-level configurable is the only carrier between tool batches: + * `loadTools` hands back a fresh object every call here, exactly as a + * real re-resolve would, so nothing can pass through shared object + * identity. Proves the authored skill id reaches `getSkillByName` on a + * later batch and that its SKILL.md body is what gets primed. + */ + const createdSkill = { + _id: SKILL_ID, + name: 'fresh-skill', + body: '---\nname: fresh-skill\ndescription: Use for fresh tests\n---\n# Fresh skill body\n', + description: 'Use for fresh tests', + fileCount: 0, + version: 1, + }; + let storedSkill: typeof createdSkill | null = null; + const createSkill = jest.fn(async () => { + storedSkill = createdSkill; + return { skill: createdSkill }; + }); + const getSkillByName = jest.fn(async () => storedSkill); + const saveSkillFileContent = jest.fn(async () => ({ + bytes: 14, + relativePath: 'references/a.md', + })); + const loadedConfigurables: Record[] = []; + const loadTools: ToolExecuteOptions['loadTools'] = jest.fn(async () => { + const loaded = { + req, + skillAuthoringAvailable: true, + fileAuthoringToolNames: new Set(['create_file', 'edit_file']), + }; + loadedConfigurables.push(loaded); + return { loadedTools: [], configurable: loaded }; + }); + const handler = createToolExecuteHandler({ + loadTools, + canCreateSkill: jest.fn(async () => true), + canEditSkill: jest.fn(async () => true), + grantSkillOwner: jest.fn(async () => undefined), + getSkillByName: getSkillByName as unknown as ToolExecuteOptions['getSkillByName'], + createSkill: createSkill as unknown as ToolExecuteOptions['createSkill'], + getSkillFileByPath: jest.fn(async () => null), + saveSkillFileContent, + }); + /** Empty catalog: nothing was accessible when the run started. */ + const runConfigurable: Record = { req, accessibleSkillIds: [] }; + + const [created] = await invokeHandlerWithConfig( + handler, + [ + { + id: 'call_create_fresh_skill', + name: 'create_file', + args: { + path: 'skills/fresh-skill/SKILL.md', + content: createdSkill.body, + }, + }, + ], + runConfigurable, + ); + const [bundled] = await invokeHandlerWithConfig( + handler, + [ + { + id: 'call_create_fresh_reference', + name: 'create_file', + args: { path: 'skills/fresh-skill/references/a.md', content: 'reference text' }, + }, + ], + runConfigurable, + ); + const [invoked] = await invokeHandlerWithConfig( + handler, + [ + { + id: 'call_invoke_fresh_skill', + name: Constants.SKILL_TOOL, + args: { skillName: 'fresh-skill' }, + }, + ], + runConfigurable, + ); + + expect(created.status).toBe('success'); + expect(created.content).toContain('Created skills/fresh-skill/SKILL.md'); + expect(created.content).toContain('Invoke it with the skill tool'); + expect(bundled.status).toBe('success'); + expect(invoked.status).toBe('success'); + expect(invoked.content).toBe('Skill "fresh-skill" loaded. Follow the instructions below.'); + expect(JSON.stringify(invoked.injectedMessages)).toContain('# Fresh skill body'); + /** Same document: the lookup is pinned to the id creation returned, so no + same-name doc can be resolved in its place. */ + expect(getSkillByName).toHaveBeenLastCalledWith('fresh-skill', [SKILL_ID], {}); + expect(runConfigurable.accessibleSkillIds).toEqual([SKILL_ID]); + expect(new Set(loadedConfigurables).size).toBe(3); + }); + + it('loads the skill it authored when a same-name deployment skill becomes accessible', async () => { + /** + * `createDeploymentSkillMethods.getSkillByName` consults the deployment + * registry before the database, and `registry.getByName` matches on name + * plus accessibility alone (it ignores the lookup options). So once a + * same-name deployment skill shares the accessible set, an unpinned + * lookup returns the deployment instructions while the create hint + * claimed the model's own skill was invocable. `getSkillByName` here + * reproduces that precedence, so the assertion is about the lookup this + * handler issues, not about the fake. + * + * Creation and invocation are separate batches because that is the only + * way the collision is reachable: a deployment skill already inside the + * authoring lookup makes the create fail as a duplicate instead, and the + * model invokes on a later turn anyway. + */ + const DEPLOYMENT_ID = new Types.ObjectId(); + const deploymentSkill = { + _id: DEPLOYMENT_ID, + name: 'shared-name', + body: '# Deployment instructions', + description: 'Deployment copy', + fileCount: 0, + version: 7, + }; + const authoredSkill = { + _id: SKILL_ID, + name: 'shared-name', + body: '---\nname: shared-name\ndescription: Authored copy\n---\n# Authored instructions\n', + description: 'Authored copy', + fileCount: 0, + version: 1, + }; + let authoredStored = false; + const getSkillByName = jest.fn( + async (name: string, accessibleIds: Array<{ toString(): string }>) => { + if (name !== 'shared-name') { + return null; + } + const ids = new Set(accessibleIds.map((id) => id.toString())); + /* Registry before database, exactly like the deployment methods. */ + if (ids.has(DEPLOYMENT_ID.toString())) { + return deploymentSkill; + } + if (authoredStored && ids.has(SKILL_ID.toString())) { + return authoredSkill; + } + return null; + }, + ); + const loadTools: ToolExecuteOptions['loadTools'] = jest.fn(async () => ({ + loadedTools: [], + configurable: { + req, + skillAuthoringAvailable: true, + fileAuthoringToolNames: new Set(['create_file', 'edit_file']), + }, + })); + const handler = createToolExecuteHandler({ + loadTools, + canCreateSkill: jest.fn(async () => true), + grantSkillOwner: jest.fn(async () => undefined), + getSkillByName: getSkillByName as unknown as ToolExecuteOptions['getSkillByName'], + createSkill: jest.fn(async () => { + authoredStored = true; + return { skill: authoredSkill }; + }) as unknown as ToolExecuteOptions['createSkill'], + }); + const runConfigurable: Record = { req, accessibleSkillIds: [] }; + + const [created] = await invokeHandlerWithConfig( + handler, + [ + { + id: 'call_create_shared_name', + name: 'create_file', + args: { path: 'skills/shared-name/SKILL.md', content: authoredSkill.body }, + }, + ], + runConfigurable, + ); + /* A later batch re-resolves per agent and brings the deployment skill + into the accessible set. */ + (runConfigurable.accessibleSkillIds as (typeof DEPLOYMENT_ID)[]).push(DEPLOYMENT_ID); + const [invoked] = await invokeHandlerWithConfig( + handler, + [ + { + id: 'call_invoke_shared_name', + name: Constants.SKILL_TOOL, + args: { skillName: 'shared-name' }, + }, + ], + runConfigurable, + ); + + expect(created.status).toBe('success'); + expect(created.content).toContain('Invoke it with the skill tool'); + expect(invoked.status).toBe('success'); + /* The hint promised the authored skill, so the authored body is what has + to reach the context. */ + const injected = JSON.stringify(invoked.injectedMessages); + expect(injected).toContain('# Authored instructions'); + expect(injected).not.toContain('# Deployment instructions'); + /* Pinned to the authored id alone, and without `preferModelInvocable`: + one candidate leaves no collision to resolve. */ + expect(getSkillByName).toHaveBeenLastCalledWith('shared-name', [SKILL_ID], {}); + }); + + it('keeps the authored id reachable after the per-batch configurable copy', async () => { + /** + * `ON_TOOL_EXECUTE` rebuilds the run configurable every batch + * (`{ ...incomingConfigurable, executionContext }`), so a map assigned + * onto that copy is discarded with it. The map is seeded on the run's own + * configurable for exactly this reason; this pins the surviving channel so + * a future change that reassigns it instead of mutating it fails here + * rather than silently unpinning cross-batch invocation. + */ + const createdSkill = { + _id: SKILL_ID, + name: 'cross-batch-skill', + body: '---\nname: cross-batch-skill\ndescription: Cross batch\n---\n# Cross batch body\n', + description: 'Cross batch', + fileCount: 0, + version: 1, + }; + let stored = false; + const getSkillByName = jest.fn(async () => (stored ? createdSkill : null)); + const loadTools: ToolExecuteOptions['loadTools'] = jest.fn(async () => ({ + loadedTools: [], + configurable: { + req, + skillAuthoringAvailable: true, + fileAuthoringToolNames: new Set(['create_file', 'edit_file']), + }, + })); + const handler = createToolExecuteHandler({ + loadTools, + canCreateSkill: jest.fn(async () => true), + grantSkillOwner: jest.fn(async () => undefined), + getSkillByName: getSkillByName as unknown as ToolExecuteOptions['getSkillByName'], + createSkill: jest.fn(async () => { + stored = true; + return { skill: createdSkill }; + }) as unknown as ToolExecuteOptions['createSkill'], + }); + const runConfigurable: Record = { req, accessibleSkillIds: [] }; + + await invokeHandlerWithConfig( + handler, + [ + { + id: 'call_create_cross_batch', + name: 'create_file', + args: { path: 'skills/cross-batch-skill/SKILL.md', content: createdSkill.body }, + }, + ], + runConfigurable, + ); + + expect(runConfigurable.authoredSkillIdsByName).toEqual({ + 'cross-batch-skill': SKILL_ID.toString(), + }); + + const [invoked] = await invokeHandlerWithConfig( + handler, + [ + { + id: 'call_invoke_cross_batch', + name: Constants.SKILL_TOOL, + args: { skillName: 'cross-batch-skill' }, + }, + ], + runConfigurable, + ); + + expect(invoked.status).toBe('success'); + expect(JSON.stringify(invoked.injectedMessages)).toContain('# Cross batch body'); + expect(getSkillByName).toHaveBeenLastCalledWith('cross-batch-skill', [SKILL_ID], {}); + }); + + it('does not advertise invocation for a skill created with disable-model-invocation', async () => { + const createdSkill = { + _id: SKILL_ID, + name: 'hidden-skill', + body: '# Hidden skill', + fileCount: 0, + version: 1, + }; + const handler = makeAuthoringHandler({ + getSkillByName: jest.fn(async () => null), + createSkill: jest.fn(async () => ({ + skill: createdSkill, + })) as unknown as ToolExecuteOptions['createSkill'], + }); + + const [result] = await invokeHandler(handler, [ + { + id: 'call_create_hidden_skill', + name: 'create_file', + args: { + path: 'skills/hidden-skill/SKILL.md', + content: + '---\nname: hidden-skill\ndescription: Use for hidden tests\ndisable-model-invocation: true\n---\n# Hidden skill\n', + }, + }, + ]); + + expect(result.status).toBe('success'); + expect(result.content).toContain('Created skills/hidden-skill/SKILL.md'); + expect(result.content).not.toContain('Invoke it with the skill tool'); + }); + + it('rejects invoking a skill created with disable-model-invocation', async () => { + const createdSkill = { + _id: SKILL_ID, + name: 'hidden-skill', + body: '# Hidden skill', + description: 'Use for hidden tests', + fileCount: 0, + version: 1, + disableModelInvocation: true, + }; + let storedSkill: typeof createdSkill | null = null; + const loadTools: ToolExecuteOptions['loadTools'] = jest.fn(async () => ({ + loadedTools: [], + configurable: { + req, + skillAuthoringAvailable: true, + fileAuthoringToolNames: new Set(['create_file', 'edit_file']), + }, + })); + const handler = createToolExecuteHandler({ + loadTools, + canCreateSkill: jest.fn(async () => true), + grantSkillOwner: jest.fn(async () => undefined), + getSkillByName: jest.fn( + async () => storedSkill, + ) as unknown as ToolExecuteOptions['getSkillByName'], + createSkill: jest.fn(async () => { + storedSkill = createdSkill; + return { skill: createdSkill }; + }) as unknown as ToolExecuteOptions['createSkill'], + }); + const runConfigurable: Record = { req, accessibleSkillIds: [] }; + + await invokeHandlerWithConfig( + handler, + [ + { + id: 'call_create_hidden_then_invoke', + name: 'create_file', + args: { + path: 'skills/hidden-skill/SKILL.md', + content: + '---\nname: hidden-skill\ndescription: Use for hidden tests\ndisable-model-invocation: true\n---\n# Hidden skill\n', + }, + }, + ], + runConfigurable, + ); + const [invoked] = await invokeHandlerWithConfig( + handler, + [ + { + id: 'call_invoke_hidden_skill', + name: Constants.SKILL_TOOL, + args: { skillName: 'hidden-skill' }, + }, + ], + runConfigurable, + ); + + expect(invoked.status).toBe('error'); + expect(invoked.errorMessage).toBe('Skill "hidden-skill" cannot be invoked by the model'); + }); + + it('rejects invoking a skill whose creation failed', async () => { + const loadTools: ToolExecuteOptions['loadTools'] = jest.fn(async () => ({ + loadedTools: [], + configurable: { + req, + skillAuthoringAvailable: true, + fileAuthoringToolNames: new Set(['create_file', 'edit_file']), + }, + })); + const handler = createToolExecuteHandler({ + loadTools, + canCreateSkill: jest.fn(async () => false), + grantSkillOwner: jest.fn(async () => undefined), + getSkillByName: jest.fn( + async () => null, + ) as unknown as ToolExecuteOptions['getSkillByName'], + createSkill: jest.fn() as unknown as ToolExecuteOptions['createSkill'], + }); + const runConfigurable: Record = { req, accessibleSkillIds: [] }; + + const [created] = await invokeHandlerWithConfig( + handler, + [ + { + id: 'call_create_denied_skill', + name: 'create_file', + args: { + path: 'skills/denied-skill/SKILL.md', + content: + '---\nname: denied-skill\ndescription: Use for denied tests\n---\n# Denied\n', + }, + }, + ], + runConfigurable, + ); + const [invoked] = await invokeHandlerWithConfig( + handler, + [ + { + id: 'call_invoke_denied_skill', + name: Constants.SKILL_TOOL, + args: { skillName: 'denied-skill' }, + }, + ], + runConfigurable, + ); + + expect(created.status).toBe('error'); + expect(created.content).not.toContain('Invoke it with the skill tool'); + expect(invoked.status).toBe('error'); + expect(invoked.errorMessage).toBe('Skill "denied-skill" not found or not accessible'); + expect(runConfigurable.accessibleSkillIds).toEqual([]); + }); + it('rejects case-colliding recognized frontmatter keys in create_file', async () => { const createSkill = jest.fn(); const handler = makeAuthoringHandler({ diff --git a/packages/api/src/agents/handlers.ts b/packages/api/src/agents/handlers.ts index 5d39bf4068..6489a26ad5 100644 --- a/packages/api/src/agents/handlers.ts +++ b/packages/api/src/agents/handlers.ts @@ -1,7 +1,11 @@ import yaml from 'js-yaml'; import { Types } from 'mongoose'; import { GraphEvents, Constants, ToolEndHandler } from '@librechat/agents'; -import { logger, normalizeSkillFrontmatterKeys } from '@librechat/data-schemas'; +import { + logger, + normalizeSkillFrontmatterKeys, + deriveStructuredFrontmatterFields, +} from '@librechat/data-schemas'; import { AGENT_BACKGROUND_COMPLETION_RESULT_MAX_CHARS_DEFAULT, hasActivePiiFields, @@ -3061,6 +3065,23 @@ function isSkillAuthoringAvailable(mergedConfigurable: Record): return mergedConfigurable.skillAuthoringAvailable === true; } +/** + * Tells the model that the skill it just created is a legal `skill` target. + * Creation neither loads nor activates the skill, so the run has no other + * signal that the name became invocable. Only reachable on runs that can + * author skills, which are exactly the runs where the `skill` tool is + * registered (see `isSkillToolAvailable`). + * + * Suppressed for `disable-model-invocation: true`, which + * `handleSkillToolCall` rejects — advertising it would send the model into a + * guaranteed error. + */ +function authoredSkillInvocationHint(frontmatter: Record | undefined): string { + return deriveStructuredFrontmatterFields(frontmatter).disableModelInvocation === true + ? '' + : ' Invoke it with the skill tool when you want its instructions loaded.'; +} + function getFileAuthoringToolNames( mergedConfigurable: Record, ): Set | undefined { @@ -3155,6 +3176,36 @@ function mergeSkillPrimedIdsByName( return Object.keys(merged).length > 0 ? merged : undefined; } +function mergeAuthoredSkillIdsByName( + base: Record | undefined, + loaded: Record | undefined, +): Record | undefined { + const loadedAuthored = loaded?.authoredSkillIdsByName as Record | undefined; + const baseAuthored = base?.authoredSkillIdsByName as Record | undefined; + const merged = { ...(loadedAuthored ?? {}), ...(baseAuthored ?? {}) }; + return Object.keys(merged).length > 0 ? merged : undefined; +} + +/** + * The `_id` this run's authoring path bound to a skill name, when it bound one. + * + * Deliberately separate from `skillPrimedIdsByName`: that map also carries + * manual (`$`) and always-apply primes and doubles as the switch that relaxes + * the `disable-model-invocation` gate for primed bodies, so widening its + * meaning would change how those primes resolve. This map carries identity + * only, for the names this run authored. + */ +function getAuthoredSkillId( + skillName: string, + mergedConfigurable: Record | undefined, +): string | undefined { + const authoredIds = mergedConfigurable?.authoredSkillIdsByName as + | Record + | undefined; + const id = authoredIds?.[skillName]; + return typeof id === 'string' && id.length > 0 ? id : undefined; +} + function mergeActiveSkillNames( base: Record | undefined, loaded: Record | undefined, @@ -3277,6 +3328,10 @@ function mergeToolConfigurables( if (skillPrimedIdsByName) { merged.skillPrimedIdsByName = skillPrimedIdsByName; } + const authoredSkillIdsByName = mergeAuthoredSkillIdsByName(base, loaded); + if (authoredSkillIdsByName) { + merged.authoredSkillIdsByName = authoredSkillIdsByName; + } const activeSkillNames = mergeActiveSkillNames(base, loaded); if (activeSkillNames) { merged.activeSkillNames = activeSkillNames; @@ -3313,6 +3368,18 @@ function rememberAuthoredSkill( configurable.skillPrimedIdsByName = primedIds; } + /** + * Recorded for every authoring resolution, including `prime: false` + * recovery: both mean this run's authoring path bound this name to this + * doc, which is the doc invocation has to load. Unlike the primed map this + * grants no gate relaxation, so recording it during recovery cannot let a + * `disable-model-invocation: true` skill slip past its gate. + */ + const authoredIds = + (configurable.authoredSkillIdsByName as Record | undefined) ?? {}; + authoredIds[skill.name] = idString; + configurable.authoredSkillIdsByName = authoredIds; + const activeSkillNames = configurable.activeSkillNames as Set | undefined; if (activeSkillNames) { activeSkillNames.add(skill.name); @@ -3630,9 +3697,10 @@ async function writeSkillMd({ } rememberAuthoredSkill([mergedConfigurable, sourceConfigurable], result.skill); const surfacedWarnings = surfaceSkillAuthoringWarnings(result.warnings); + const invocationHint = authoredSkillInvocationHint(structured.frontmatter); return successResult( tc, - `Created ${SKILL_FILE_PREFIX}${skillName}/${SKILL_MD} (${content.length} chars).${surfacedWarnings?.contentSuffix ?? ''}`, + `Created ${SKILL_FILE_PREFIX}${skillName}/${SKILL_MD} (${content.length} chars).${surfacedWarnings?.contentSuffix ?? ''}${invocationHint}`, { path: `${SKILL_FILE_PREFIX}${skillName}/${SKILL_MD}`, bytes_written: Buffer.byteLength(content, 'utf8'), @@ -5018,16 +5086,34 @@ async function handleSkillToolCall( } const accessibleIds = (mergedConfigurable?.accessibleSkillIds as Types.ObjectId[]) ?? []; - /* `preferModelInvocable` keeps name-collision resolution aligned with - the catalog: a newer `disable-model-invocation: true` duplicate - can't shadow the cataloged invocable doc. Model-only + /* On a name this run's authoring path bound to a specific doc, pin the + accessible set to ONLY that `_id`, exactly as the `read_file` path + pins to a primed `_id`. `getSkillByName` resolves deployment skills + from the registry before the database and matches on name plus + accessibility alone, so a same-name deployment skill sharing the + accessible set would otherwise shadow the doc just authored — the + model would be told its creation is invocable and then be handed + different instructions. Pinning also drops `preferModelInvocable`, + matching `resolveSkillForAuthoring`: with one candidate there is no + collision to resolve, and the `disable-model-invocation` gate below + must still see the authored doc rather than a same-name twin. + + `preferModelInvocable` keeps name-collision resolution aligned with + the catalog otherwise: a newer `disable-model-invocation: true` + duplicate can't shadow the cataloged invocable doc. Model-only (`userInvocable: false`) skills are intentionally still resolvable here — they're valid model-invocation targets. Falls back to the newest match so the disabled-only case still resolves and the gate below fires its explicit error. */ - const skill = await getSkillByName(args.skillName, accessibleIds, { - preferModelInvocable: true, - }); + const authoredIdString = getAuthoredSkillId(args.skillName, mergedConfigurable); + const lookupAccessibleIds = authoredIdString + ? [new Types.ObjectId(authoredIdString)] + : accessibleIds; + const skill = await getSkillByName( + args.skillName, + lookupAccessibleIds, + authoredIdString ? {} : { preferModelInvocable: true }, + ); if (!skill) { return { @@ -5359,6 +5445,18 @@ export function createToolExecuteHandler(options: ToolExecuteOptions): EventHand ).executionContext; // Only the SDK-owned batch field may establish a child execution. Runtime // configurable and callback metadata can otherwise carry inherited values. + /** + * Authored-skill identity has to outlive the per-batch copy below, which + * is what makes a skill created in one batch resolvable in the next. + * A shallow copy shares object references, so seeding the map on the + * run's own configurable lets `rememberAuthoredSkill` mutate it in place + * and later batches observe it, exactly as the shared + * `accessibleSkillIds` array already crosses batches. A fresh map + * assigned onto the copy would be discarded with the copy. + */ + if (incomingConfigurable != null && incomingConfigurable.authoredSkillIdsByName == null) { + incomingConfigurable.authoredSkillIdsByName = {}; + } const configurable: Record | undefined = incomingConfigurable == null ? undefined : { ...incomingConfigurable, executionContext }; const metadata: Record | undefined = diff --git a/packages/api/src/agents/initialize.ts b/packages/api/src/agents/initialize.ts index 79ae24e74a..9a09ac949c 100644 --- a/packages/api/src/agents/initialize.ts +++ b/packages/api/src/agents/initialize.ts @@ -2303,12 +2303,19 @@ export async function initializeAgent( let executableSkillIds = params.accessibleSkillIds; let activeSkillNames: Set | undefined; const { accessibleSkillIds } = params; - if (accessibleSkillIds && accessibleSkillIds.length > 0) { + /** + * Authoring runs go through catalog injection even with nothing accessible: + * `injectSkillCatalog` owns the `skill` tool registration, and a model that + * can write `skills/{skillName}/SKILL.md` needs the tool bound at init to + * invoke what it creates later in the same conversation. + */ + if ((accessibleSkillIds && accessibleSkillIds.length > 0) || skillAuthoringAvailable) { const skillResult = await injectSkillCatalog({ agent, toolDefinitions, toolRegistry, - accessibleSkillIds, + accessibleSkillIds: accessibleSkillIds ?? [], + skillAuthoringAvailable, contextWindowTokens: Number(agentMaxContextTokens) || 200_000, listSkillsByAccess: db?.listSkillsByAccess, codeEnvAvailable: effectiveCodeEnvAvailable, diff --git a/packages/api/src/agents/skills.ts b/packages/api/src/agents/skills.ts index beb5373b72..d080628cc3 100644 --- a/packages/api/src/agents/skills.ts +++ b/packages/api/src/agents/skills.ts @@ -10,8 +10,8 @@ import type { import type { LCToolRegistry, LCTool, InjectedMessage } from '@librechat/agents'; import type { BaseMessage } from '@librechat/agents/langchain/messages'; import type { Types } from 'mongoose'; +import { getSkillToolDefinition, isSkillToolAvailable, registerCodeExecutionTools } from './tools'; import { createSkillContentDigest } from './compatibility'; -import { registerCodeExecutionTools } from './tools'; import { logAxiosError } from '~/utils'; /** @@ -449,6 +449,12 @@ export interface InjectSkillCatalogParams { defaultActiveOnShare?: boolean; /** Admin-configured cap on the model-visible catalog. Defaults to 100. */ maxCatalogSkills?: number; + /** + * When true, the model may author skills this run, so the `skill` tool + * registers even with an empty catalog and its guidance accepts a name the + * model creates mid-run. See `isSkillToolAvailable`. + */ + skillAuthoringAvailable?: boolean; /** Read-only catalog snapshot preloaded for current-policy inspection. */ resolvedCatalog?: ResolvedSkillCatalog; } @@ -676,6 +682,7 @@ export async function injectSkillCatalog( defaultActiveOnShare = false, maxCatalogSkills, resolvedCatalog, + skillAuthoringAvailable = false, } = params; const { activeSkills, catalogLimit, visibleCount, reachedEnd } = resolvedCatalog ?? @@ -688,7 +695,14 @@ export async function injectSkillCatalog( maxCatalogSkills, })); - if (activeSkills.length === 0) { + /** + * Nothing to catalog and nothing the model could author: skip registration + * entirely rather than spend description tokens on tools with no targets. + * Authoring runs fall through — the `skill` tool still registers below so a + * skill created mid-run is invocable, and `read_file` stays available for + * its bundled files. + */ + if (activeSkills.length === 0 && !skillAuthoringAvailable) { return { toolDefinitions: inputDefs, skillCount: 0, @@ -752,9 +766,10 @@ export async function injectSkillCatalog( /** * Catalog text is gated on the visible subset — `disable-model-invocation` * skills cost zero context tokens. When no visible skills exist, the - * model gets no catalog and the `skill` tool is omitted from the - * registry (registering it would burn description tokens for a tool - * the model has no targets for). `read_file` and `bash_tool` are still + * model gets no catalog, and the `skill` tool is omitted from the + * registry unless this run can author one (registering it otherwise + * would burn description tokens for a tool the model has no targets + * for). `read_file` and `bash_tool` are still * registered though: manually-primed disabled skills can have their * SKILL.md body in context referring to `references/*` and `scripts/*`, * and those reads would otherwise be impossible. @@ -788,14 +803,16 @@ export async function injectSkillCatalog( } } - const skillToolDef: LCTool = { - name: SkillToolDefinition.name, - description: SkillToolDefinition.description, - parameters: SkillToolDefinition.parameters as unknown as LCTool['parameters'], - }; + const skillToolDef = getSkillToolDefinition(skillAuthoringAvailable); + const skillToolAvailable = isSkillToolAvailable({ + modelInvocableSkillsAvailable: catalogVisibleSkills.length > 0, + skillAuthoringAvailable, + }); /** - * `skill` tool is conditional on having anything for the model to invoke. + * `skill` tool is conditional on having anything for the model to invoke — + * a catalog-visible skill, or an authoring run where the model can create + * one and invoke it in the same conversation. * `read_file` + `bash_tool` go through `registerCodeExecutionTools` so * a prior registration from `initializeAgent` (for the `execute_code` * capability) upgrades to the skill-aware `read_file` definition without @@ -805,8 +822,22 @@ export async function injectSkillCatalog( * `codeEnvAvailable` as before. */ let workingDefs: LCTool[] = [...(inputDefs ?? [])]; - if (catalogVisibleSkills.length > 0) { - workingDefs.push(skillToolDef); + if (skillToolAvailable) { + /** + * Replace rather than skip, so the registry the host handler resolves and + * the array the model reads never disagree about which variant is live. + * Skipping would leave an earlier catalog-only definition telling an + * authoring run's model that a skill it just created is an invalid name — + * the exact failure this registration exists to prevent — while the + * registry claimed otherwise. Mirrors how `registerCodeExecutionTools` + * upgrades a code-only `read_file` in place instead of suppressing it. + */ + const existingIndex = workingDefs.findIndex((def) => def.name === skillToolDef.name); + if (existingIndex >= 0) { + workingDefs[existingIndex] = skillToolDef; + } else { + workingDefs.push(skillToolDef); + } toolRegistry?.set(skillToolDef.name, skillToolDef); } @@ -835,10 +866,9 @@ export async function injectSkillCatalog( }); workingDefs = codeExecResult.toolDefinitions; - const toolNames = - catalogVisibleSkills.length > 0 - ? [skillToolDef.name, ReadFileToolDefinition.name] - : [ReadFileToolDefinition.name]; + const toolNames = skillToolAvailable + ? [skillToolDef.name, ReadFileToolDefinition.name] + : [ReadFileToolDefinition.name]; return { toolDefinitions: workingDefs, diff --git a/packages/api/src/agents/tools.spec.ts b/packages/api/src/agents/tools.spec.ts index 96bfa32cdb..3764d1045c 100644 --- a/packages/api/src/agents/tools.spec.ts +++ b/packages/api/src/agents/tools.spec.ts @@ -21,6 +21,26 @@ jest.mock('@librechat/agents', () => ({ }, responseFormat: 'content', }, + SkillToolDefinition: { + name: 'skill', + description: `Invoke a skill from the user's library. + +CONSTRAINTS: +- Do not invoke a skill that is already active in this conversation. +- Skill names come from the catalog only. Do not guess names.`, + parameters: { + type: 'object', + properties: { + intent: { type: 'string', description: 'intent' }, + skillName: { + type: 'string', + description: 'Must match a name from the "Available Skills" section.', + }, + args: { type: 'string', description: 'Optional freeform arguments string.' }, + }, + required: ['skillName'], + }, + }, BashExecutionToolDefinition: { name: 'bash_tool', description: 'bash', @@ -60,6 +80,10 @@ import { FILE_AUTHORING_TOOL_NAMES, isFileAuthoringToolDefinition, isCodeSessionToolName, + isSkillToolAvailable, + getSkillToolDefinition, + buildAuthoringSkillToolDescription, + buildAuthoringSkillToolParameters, } from './tools'; /** Portable ceiling for OpenAI-compatible tool description validators. */ @@ -342,6 +366,16 @@ describe('buildHistoricalToolNames', () => { ).toEqual(new Set(['read_file'])); }); + it('exposes the skill invocation tool on an authoring run with an empty catalog', () => { + expect( + buildHistoricalToolNames({ + skillsAvailable: false, + skillFileAccessAvailable: false, + skillAuthoringAvailable: true, + }), + ).toEqual(new Set(['skill', 'read_file', 'create_file', 'edit_file'])); + }); + it('normalizes Action names and their options', () => { expect( buildHistoricalToolNames({ @@ -430,6 +464,187 @@ describe('buildHistoricalToolNames', () => { }); }); +describe('isSkillToolAvailable', () => { + it('registers for a visible catalog, for an authoring run, and for neither', () => { + expect(isSkillToolAvailable({ modelInvocableSkillsAvailable: true })).toBe(true); + expect(isSkillToolAvailable({ skillAuthoringAvailable: true })).toBe(true); + expect( + isSkillToolAvailable({ modelInvocableSkillsAvailable: true, skillAuthoringAvailable: true }), + ).toBe(true); + expect( + isSkillToolAvailable({ + modelInvocableSkillsAvailable: false, + skillAuthoringAvailable: false, + }), + ).toBe(false); + expect(isSkillToolAvailable({})).toBe(false); + }); +}); + +describe('getSkillToolDefinition', () => { + function skillNameDescription(definition: LCTool): string { + const parameters = definition.parameters as + | { properties?: { skillName?: { description?: string } } } + | undefined; + return parameters?.properties?.skillName?.description ?? ''; + } + + it('keeps the catalog-only guidance when the run cannot author skills', () => { + const definition = getSkillToolDefinition(false); + + expect(definition.name).toBe('skill'); + expect(definition.description).toContain('Skill names come from the catalog only'); + expect(skillNameDescription(definition)).toBe( + 'Must match a name from the "Available Skills" section.', + ); + }); + + it('accepts a skill authored during the run when the run can author skills', () => { + const definition = getSkillToolDefinition(true); + + expect(definition.description).not.toContain('Skill names come from the catalog only'); + expect(definition.description).toContain('a skill you created in this conversation'); + expect(definition.description).toContain('Creating a skill does not load it'); + expect(definition.description).toContain( + 'Do not invoke a skill that is already active in this conversation.', + ); + expect(skillNameDescription(definition)).toContain( + 'the name of a skill you created in this conversation', + ); + }); + + it('leaves the rest of the schema and the non-authoring definition untouched', () => { + const authoring = getSkillToolDefinition(true); + const parameters = authoring.parameters as { + type?: string; + required?: string[]; + properties?: Record; + }; + + expect(parameters.type).toBe('object'); + expect(parameters.required).toEqual(['skillName']); + expect(Object.keys(parameters.properties ?? {})).toEqual(['intent', 'skillName', 'args']); + expect(parameters.properties?.args?.description).toBe('Optional freeform arguments string.'); + expect(skillNameDescription(getSkillToolDefinition(false))).toBe( + 'Must match a name from the "Available Skills" section.', + ); + expect(getSkillToolDefinition(true)).toBe(authoring); + }); +}); + +describe('buildAuthoringSkillToolDescription', () => { + it('rewrites the catalog-only constraint in place, keeping every other one', () => { + const base = [ + 'Invoke a skill.', + '', + 'CONSTRAINTS:', + '- Do not invoke a skill that is already active in this conversation.', + '- Skill names come from the catalog only. Do not guess names.', + ].join('\n'); + + const result = buildAuthoringSkillToolDescription(base); + + expect(result).not.toContain('Skill names come from the catalog only'); + expect(result).toContain( + '- Do not invoke a skill that is already active in this conversation.', + ); + expect(result).toContain('a skill you created in this conversation'); + /* Rewritten in place, so the guidance stays inside CONSTRAINTS rather than + trailing after it. */ + expect( + result.endsWith( + 'Creating a skill does not load it. Invoke it here when you want to follow its instructions.', + ), + ).toBe(true); + }); + + it('appends the guidance when the SDK no longer carries that sentence', () => { + /* Drift branch: the sentence was reworded or dropped upstream. The authored + -skill guidance must still reach the model, appended rather than lost. */ + const drifted = [ + 'Invoke a skill.', + '', + 'CONSTRAINTS:', + '- Do not invoke a skill that is already active in this conversation.', + ].join('\n'); + + const result = buildAuthoringSkillToolDescription(drifted); + + expect(result.startsWith(drifted)).toBe(true); + expect(result).toContain('a skill you created in this conversation'); + expect(result).toContain('Creating a skill does not load it'); + }); +}); + +describe('buildAuthoringSkillToolParameters', () => { + it('retargets skillName guidance while preserving the rest of the schema', () => { + const base = { + type: 'object', + properties: { + intent: { type: 'string', description: 'intent' }, + skillName: { type: 'string', description: 'catalog only' }, + }, + required: ['skillName'], + } as unknown as LCTool['parameters']; + + const result = buildAuthoringSkillToolParameters(base) as unknown as { + type?: string; + required?: string[]; + properties?: Record; + }; + + expect(result.properties?.skillName?.description).toContain( + 'a skill you created in this conversation', + ); + /* The property keeps its own non-description fields, and its siblings are + untouched. */ + expect(result.properties?.skillName?.type).toBe('string'); + expect(result.properties?.intent?.description).toBe('intent'); + expect(result.type).toBe('object'); + expect(result.required).toEqual(['skillName']); + }); + + it('returns the schema unchanged when the SDK has no skillName property', () => { + /* Drift branch: the installed package disagrees with the types it shipped. + Losing the authored-skill hint beats failing the packages/api import, + which is what an unguarded dereference at module load would do. */ + const base = { + type: 'object', + properties: { intent: { type: 'string' } }, + } as unknown as LCTool['parameters']; + + expect(buildAuthoringSkillToolParameters(base)).toBe(base); + }); +}); + +describe('installed @librechat/agents skill tool canary', () => { + /** + * The two things the authoring variant reads off the real SDK export. This + * suite mocks `@librechat/agents`, so these assertions deliberately reach + * past the mock to the installed package. + * + * When either fails, do not "fix" the test: the authoring variant is silently + * degraded against that version. A moved sentence leaves the reworded + * catalog-only constraint standing beside guidance that contradicts it (the + * append branch above), and a moved `skillName` property drops the authored + * -skill wording from the parameter. Re-point `CATALOG_ONLY_SKILL_CONSTRAINT` + * in `tools.ts` at the new text instead. + */ + it('still ships the constraint sentence and skillName property the variant rewrites', () => { + const { SkillToolDefinition } = jest.requireActual('@librechat/agents') as { + SkillToolDefinition: { + description: string; + parameters: { properties?: Record }; + }; + }; + + expect(SkillToolDefinition.description).toContain( + '- Skill names come from the catalog only. Do not guess names.', + ); + expect(SkillToolDefinition.parameters.properties?.skillName).toBeDefined(); + }); +}); + describe('registerCodeExecutionTools', () => { it('advertises selected named actions to the model', () => { const result = registerCodeExecutionTools({ diff --git a/packages/api/src/agents/tools.ts b/packages/api/src/agents/tools.ts index 3b4827eae7..8dd9742dbd 100644 --- a/packages/api/src/agents/tools.ts +++ b/packages/api/src/agents/tools.ts @@ -10,6 +10,7 @@ import { CODE_EXECUTION_TOOLS, BashExecutionToolDefinition, ReadFileToolDefinition, + SkillToolDefinition, buildBashExecutionToolDescription, } from '@librechat/agents'; import type { @@ -123,6 +124,27 @@ export interface BuildHistoricalToolNamesConfig { backgroundToolsAvailable?: boolean; } +export interface SkillToolAvailabilityConfig { + /** True when at least one catalog-visible (model-invocable) skill resolved for the run. */ + modelInvocableSkillsAvailable?: boolean; + /** True when the model may create or edit skill files during the run. */ + skillAuthoringAvailable?: boolean; +} + +/** + * Single rule for whether the `skill` tool reaches the model, shared by live + * registration (`injectSkillCatalog`) and the lazy-history prediction below so + * the two cannot disagree about a run's tool names. + * + * Authoring runs register it even with an empty catalog: a skill the model + * creates mid-run becomes a valid invocation target, and tool definitions bind + * at initialization, so a run that only learned about the skill afterwards + * would have no way to invoke what it just wrote. + */ +export function isSkillToolAvailable(config: SkillToolAvailabilityConfig): boolean { + return config.modelInvocableSkillsAvailable === true || config.skillAuthoringAvailable === true; +} + /** Derives the model-facing names an unresolved lazy agent can expose without loading it. */ export function buildHistoricalToolNames(config: BuildHistoricalToolNamesConfig): Set { const configuredToolNames = [ @@ -163,8 +185,13 @@ export function buildHistoricalToolNames(config: BuildHistoricalToolNamesConfig) toolNames.add('set_memory'); toolNames.add('delete_memory'); } - if (config.skillsAvailable === true) { - toolNames.add('skill'); + if ( + isSkillToolAvailable({ + modelInvocableSkillsAvailable: config.skillsAvailable, + skillAuthoringAvailable: config.skillAuthoringAvailable, + }) + ) { + toolNames.add(SkillToolDefinition.name); } if ((config.skillFileAccessAvailable ?? config.skillsAvailable) === true) { toolNames.add('read_file'); @@ -545,6 +572,94 @@ function createAttachedWorkspaceReadFileDef(includeSkillFileInstructions: boolea const ATTACHED_CODE_READ_FILE_DEF = createAttachedWorkspaceReadFileDef(false); const ATTACHED_SKILL_READ_FILE_DEF = createAttachedWorkspaceReadFileDef(true); +/** + * The SDK constraint the authoring variant rewrites. Left alone it tells the + * model that catalog names are the only legal `skillName`, which is false for a + * run that can author skills, and worst when the catalog is empty and the only + * reachable skill is the one the model just created. + */ +const CATALOG_ONLY_SKILL_CONSTRAINT = + '- Skill names come from the catalog only. Do not guess names.'; + +const AUTHORED_SKILL_CONSTRAINTS = `- Skill names come from the catalog, or from a skill you created in this conversation with create_file at "skills/{skillName}/SKILL.md". Do not guess any other name. +- Creating a skill does not load it. Invoke it here when you want to follow its instructions.`; + +const AUTHORED_SKILL_NAME_DESCRIPTION = + 'The kebab-case identifier of the skill to invoke (e.g. "financial-analyzer", "meeting-notes"). Must match a name from the "Available Skills" section, or the name of a skill you created in this conversation.'; + +/** + * Rewrites in place while the SDK still ships the catalog-only constraint, so + * every other constraint it declares survives; appends otherwise, so the + * authored-skill guidance reaches the model even if that text moves. + * + * Exported for the drift tests: appending leaves a reworded catalog-only + * sentence standing next to guidance that contradicts it, so both branches have + * to be pinned rather than inferred. `tools.spec.ts` also asserts the real SDK + * export still carries the sentence, which fails CI on the bump that would + * quietly move this onto the append branch. + */ +export function buildAuthoringSkillToolDescription(baseDescription: string): string { + return baseDescription.includes(CATALOG_ONLY_SKILL_CONSTRAINT) + ? baseDescription.replace(CATALOG_ONLY_SKILL_CONSTRAINT, AUTHORED_SKILL_CONSTRAINTS) + : `${baseDescription}\n${AUTHORED_SKILL_CONSTRAINTS}`; +} + +/** The shape the authoring variant needs from the SDK's `skill` schema. */ +interface SkillToolParametersView { + properties?: Record; +} + +/** + * Retargets the SDK's `skillName` guidance at skills authored this run, leaving + * the rest of the schema alone. + * + * Takes the schema rather than reading the module import so both branches are + * reachable from a test. The property is non-optional in the SDK's types, so + * this reads it through a widened view: an installed package can disagree with + * the types it shipped, and this definition is built at module load, where an + * unguarded dereference would fail the whole `packages/api` import rather than + * one tool's wording. + */ +export function buildAuthoringSkillToolParameters( + baseParameters: LCTool['parameters'], +): LCTool['parameters'] { + const view = baseParameters as unknown as SkillToolParametersView; + const skillName = view.properties?.skillName; + if (skillName == null) { + return baseParameters; + } + return { + ...view, + properties: { + ...view.properties, + skillName: { ...skillName, description: AUTHORED_SKILL_NAME_DESCRIPTION }, + }, + } as unknown as LCTool['parameters']; +} + +const SKILL_TOOL_DEF: LCTool = Object.freeze({ + name: SkillToolDefinition.name, + description: SkillToolDefinition.description, + parameters: SkillToolDefinition.parameters as unknown as LCTool['parameters'], +}) as LCTool; + +const AUTHORING_SKILL_TOOL_DEF: LCTool = Object.freeze({ + name: SkillToolDefinition.name, + description: buildAuthoringSkillToolDescription(SkillToolDefinition.description), + parameters: buildAuthoringSkillToolParameters( + SkillToolDefinition.parameters as unknown as LCTool['parameters'], + ), +}) as LCTool; + +/** + * Model-facing `skill` definition for the run. Authoring runs get the variant + * whose guidance accepts a name the model created during the run; every other + * run gets the SDK definition untouched. + */ +export function getSkillToolDefinition(skillAuthoringAvailable: boolean): LCTool { + return skillAuthoringAvailable ? AUTHORING_SKILL_TOOL_DEF : SKILL_TOOL_DEF; +} + const SEARCH_WORKSPACE_TOOL_DEF: LCTool = Object.freeze({ name: SEARCH_WORKSPACE_TOOL_NAME, toolType: 'builtin',