@acontext/acontext 0.0.19 → 0.0.20

package/dist/agent/skill.d.ts

@@ -2,15 +2,49 @@
  * Skill tools for agent operations.
  */
 import { AcontextClient } from '../client';
+import { Skill } from '../types';
 import { AbstractBaseTool, BaseContext, BaseToolPool } from './base';
+/**
+ * Context for skill tools with preloaded skill name mapping.
+ */
 export interface SkillContext extends BaseContext {
     client: AcontextClient;
+    skills: Map<string, Skill>;
+}
+/**
+ * Create a SkillContext by preloading skills from a list of skill IDs.
+ *
+ * @param client - The Acontext client instance.
+ * @param skillIds - List of skill UUIDs to preload.
+ * @returns SkillContext with preloaded skills mapped by name.
+ * @throws Error if duplicate skill names are found.
+ */
+export declare function createSkillContext(client: AcontextClient, skillIds: string[]): Promise<SkillContext>;
+/**
+ * Get a skill by name from the preloaded skills.
+ *
+ * @param ctx - The skill context.
+ * @param skillName - The name of the skill.
+ * @returns The Skill object.
+ * @throws Error if the skill is not found in the context.
+ */
+export declare function getSkillFromContext(ctx: SkillContext, skillName: string): Skill;
+/**
+ * Return list of available skill names in this context.
+ */
+export declare function listSkillNamesFromContext(ctx: SkillContext): string[];
+export declare class ListSkillsTool extends AbstractBaseTool {
+    readonly name = "list_skills";
+    readonly description = "List all available skills in the current context with their names and descriptions.";
+    readonly arguments: {};
+    readonly requiredArguments: string[];
+    execute(ctx: SkillContext, _llmArguments: Record<string, unknown>): Promise<string>;
 }
 export declare class GetSkillTool extends AbstractBaseTool {
     readonly name = "get_skill";
-    readonly description = "Get a skill by its name. Return the skill information including the relative paths of the files and their mime type categories";
+    readonly description = "Get a skill by its name. Returns the skill information including the relative paths of the files and their mime type categories.";
     readonly arguments: {
-        name: {
+        skill_name: {
             type: string;
             description: string;
         };
@@ -20,7 +54,7 @@ export declare class GetSkillTool extends AbstractBaseTool {
 }
 export declare class GetSkillFileTool extends AbstractBaseTool {
     readonly name = "get_skill_file";
-    readonly description = "Get a file from a skill by name. The file_path should be a relative path within the skill (e.g., 'scripts/extract_text.json'). ";
+    readonly description: string;
     readonly arguments: {
         skill_name: {
             type: string;
@@ -39,6 +73,13 @@ export declare class GetSkillFileTool extends AbstractBaseTool {
     execute(ctx: SkillContext, llmArguments: Record<string, unknown>): Promise<string>;
 }
 export declare class SkillToolPool extends BaseToolPool {
-    formatContext(client: AcontextClient): SkillContext;
+    /**
+     * Create a SkillContext by preloading skills from a list of skill IDs.
+     *
+     * @param client - The Acontext client instance.
+     * @param skillIds - List of skill UUIDs to preload.
+     * @returns Promise resolving to SkillContext with preloaded skills mapped by name.
+     */
+    formatContext(client: AcontextClient, skillIds: string[]): Promise<SkillContext>;
 }
 export declare const SKILL_TOOLS: SkillToolPool;

package/dist/agent/skill.js

@@ -3,27 +3,95 @@
  * Skill tools for agent operations.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SKILL_TOOLS = exports.SkillToolPool = exports.GetSkillFileTool = exports.GetSkillTool = void 0;
+exports.SKILL_TOOLS = exports.SkillToolPool = exports.GetSkillFileTool = exports.GetSkillTool = exports.ListSkillsTool = void 0;
+exports.createSkillContext = createSkillContext;
+exports.getSkillFromContext = getSkillFromContext;
+exports.listSkillNamesFromContext = listSkillNamesFromContext;
 const base_1 = require("./base");
+/**
+ * Create a SkillContext by preloading skills from a list of skill IDs.
+ *
+ * @param client - The Acontext client instance.
+ * @param skillIds - List of skill UUIDs to preload.
+ * @returns SkillContext with preloaded skills mapped by name.
+ * @throws Error if duplicate skill names are found.
+ */
+async function createSkillContext(client, skillIds) {
+    const skills = new Map();
+    for (const skillId of skillIds) {
+        const skill = await client.skills.get(skillId);
+        if (skills.has(skill.name)) {
+            const existingSkill = skills.get(skill.name);
+            throw new Error(`Duplicate skill name '${skill.name}' found. ` +
+                `Existing ID: ${existingSkill.id}, New ID: ${skill.id}`);
+        }
+        skills.set(skill.name, skill);
+    }
+    return { client, skills };
+}
+/**
+ * Get a skill by name from the preloaded skills.
+ *
+ * @param ctx - The skill context.
+ * @param skillName - The name of the skill.
+ * @returns The Skill object.
+ * @throws Error if the skill is not found in the context.
+ */
+function getSkillFromContext(ctx, skillName) {
+    const skill = ctx.skills.get(skillName);
+    if (!skill) {
+        const available = ctx.skills.size > 0 ? Array.from(ctx.skills.keys()).join(', ') : '[none]';
+        throw new Error(`Skill '${skillName}' not found in context. Available skills: ${available}`);
+    }
+    return skill;
+}
+/**
+ * Return list of available skill names in this context.
+ */
+function listSkillNamesFromContext(ctx) {
+    return Array.from(ctx.skills.keys());
+}
+class ListSkillsTool extends base_1.AbstractBaseTool {
+    constructor() {
+        super(...arguments);
+        this.name = 'list_skills';
+        this.description = 'List all available skills in the current context with their names and descriptions.';
+        this.arguments = {};
+        this.requiredArguments = [];
+    }
+    async execute(ctx, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _llmArguments) {
+        if (ctx.skills.size === 0) {
+            return 'No skills available in the current context.';
+        }
+        const skillList = [];
+        for (const [skillName, skill] of ctx.skills.entries()) {
+            skillList.push(`- ${skillName}: ${skill.description}`);
+        }
+        return `Available skills (${ctx.skills.size}):\n${skillList.join('\n')}`;
+    }
+}
+exports.ListSkillsTool = ListSkillsTool;
 class GetSkillTool extends base_1.AbstractBaseTool {
     constructor() {
         super(...arguments);
         this.name = 'get_skill';
-        this.description = 'Get a skill by its name. Return the skill information including the relative paths of the files and their mime type categories';
+        this.description = 'Get a skill by its name. Returns the skill information including the relative paths of the files and their mime type categories.';
         this.arguments = {
-            name: {
+            skill_name: {
                 type: 'string',
-                description: 'The name of the skill (unique within project).',
+                description: 'The name of the skill.',
             },
         };
-        this.requiredArguments = ['name'];
+        this.requiredArguments = ['skill_name'];
     }
     async execute(ctx, llmArguments) {
-        const name = llmArguments.name;
-        if (!name) {
-            throw new Error('name is required');
+        const skillName = llmArguments.skill_name;
+        if (!skillName) {
+            throw new Error('skill_name is required');
         }
-        const skill = await ctx.client.skills.getByName(name);
+        const skill = getSkillFromContext(ctx, skillName);
         const fileCount = skill.file_index.length;
         // Format all files with path and MIME type
         let fileList;
@@ -38,9 +106,7 @@ class GetSkillTool extends base_1.AbstractBaseTool {
         return (`Skill: ${skill.name} (ID: ${skill.id})\n` +
             `Description: ${skill.description}\n` +
             `Files: ${fileCount} file(s)\n` +
-            `${fileList}\n` +
-            `Created: ${skill.created_at}\n` +
-            `Updated: ${skill.updated_at}`);
+            `${fileList}`);
     }
 }
 exports.GetSkillTool = GetSkillTool;
@@ -48,7 +114,8 @@ class GetSkillFileTool extends base_1.AbstractBaseTool {
     constructor() {
         super(...arguments);
         this.name = 'get_skill_file';
-        this.description = "Get a file from a skill by name. The file_path should be a relative path within the skill (e.g., 'scripts/extract_text.json'). ";
+        this.description = "Get a file from a skill by name. The file_path should be a relative path within the skill (e.g., 'scripts/extract_text.json')." +
+            'Tips: SKILL.md is the first file you should read to understand the full picture of this skill\'s content.';
         this.arguments = {
             skill_name: {
                 type: 'string',
@@ -69,14 +136,15 @@ class GetSkillFileTool extends base_1.AbstractBaseTool {
         const skillName = llmArguments.skill_name;
         const filePath = llmArguments.file_path;
         const expire = llmArguments.expire;
-        if (!filePath) {
-            throw new Error('file_path is required');
-        }
         if (!skillName) {
             throw new Error('skill_name is required');
         }
-        const result = await ctx.client.skills.getFileByName({
-            skillName,
+        if (!filePath) {
+            throw new Error('file_path is required');
+        }
+        const skill = getSkillFromContext(ctx, skillName);
+        const result = await ctx.client.skills.getFile({
+            skillId: skill.id,
             filePath,
             expire: expire || null,
         });
@@ -100,13 +168,19 @@ class GetSkillFileTool extends base_1.AbstractBaseTool {
 }
 exports.GetSkillFileTool = GetSkillFileTool;
 class SkillToolPool extends base_1.BaseToolPool {
-    formatContext(client) {
-        return {
-            client,
-        };
+    /**
+     * Create a SkillContext by preloading skills from a list of skill IDs.
+     *
+     * @param client - The Acontext client instance.
+     * @param skillIds - List of skill UUIDs to preload.
+     * @returns Promise resolving to SkillContext with preloaded skills mapped by name.
+     */
+    async formatContext(client, skillIds) {
+        return createSkillContext(client, skillIds);
     }
 }
 exports.SkillToolPool = SkillToolPool;
 exports.SKILL_TOOLS = new SkillToolPool();
+exports.SKILL_TOOLS.addTool(new ListSkillsTool());
 exports.SKILL_TOOLS.addTool(new GetSkillTool());
 exports.SKILL_TOOLS.addTool(new GetSkillFileTool());

package/dist/resources/skills.d.ts

@@ -29,10 +29,28 @@ export declare class SkillsAPI {
         cursor?: string | null;
         timeDesc?: boolean | null;
     }): Promise<ListSkillsOutput>;
-    getByName(name: string): Promise<Skill>;
+    /**
+     * Get a skill by its ID.
+     *
+     * @param skillId - The UUID of the skill
+     * @returns Skill containing the full skill information including file_index
+     */
+    get(skillId: string): Promise<Skill>;
     delete(skillId: string): Promise<void>;
-    getFileByName(options: {
-        skillName: string;
+    /**
+     * Get a file from a skill by skill ID.
+     *
+     * The backend automatically returns content for parseable text files, or a presigned URL
+     * for non-parseable files (binary, images, etc.).
+     *
+     * @param options - File retrieval options
+     * @param options.skillId - The UUID of the skill
+     * @param options.filePath - Relative path to the file within the skill (e.g., 'scripts/extract_text.json')
+     * @param options.expire - URL expiration time in seconds (defaults to 900 / 15 minutes)
+     * @returns GetSkillFileResp containing the file path, MIME type, and either content or URL
+     */
+    getFile(options: {
+        skillId: string;
         filePath: string;
         expire?: number | null;
     }): Promise<GetSkillFileResp>;

package/dist/resources/skills.js

@@ -4,7 +4,6 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SkillsAPI = void 0;
-const zod_1 = require("zod");
 const uploads_1 = require("../uploads");
 const utils_1 = require("../utils");
 const types_1 = require("../types");
@@ -42,12 +41,6 @@ class SkillsAPI {
      *          along with pagination information (next_cursor and has_more)
      */
     async list_catalog(options) {
-        // Parse API response (contains full Skill objects)
-        const apiResponseSchema = zod_1.z.object({
-            items: zod_1.z.array(types_1.SkillSchema),
-            next_cursor: zod_1.z.string().nullable().optional(),
-            has_more: zod_1.z.boolean(),
-        });
         // Use 100 as default for catalog listing (only name and description, lightweight)
         const effectiveLimit = options?.limit ?? 100;
         const params = (0, utils_1.buildParams)({
@@ -59,29 +52,36 @@ class SkillsAPI {
         const data = await this.requester.request('GET', '/agent_skills', {
             params: Object.keys(params).length > 0 ? params : undefined,
         });
-        const apiResponse = apiResponseSchema.parse(data);
-        // Convert to catalog format (name and description only)
-        return types_1.ListSkillsOutputSchema.parse({
-            items: apiResponse.items.map((skill) => ({
-                name: skill.name,
-                description: skill.description,
-            })),
-            next_cursor: apiResponse.next_cursor ?? null,
-            has_more: apiResponse.has_more,
-        });
+        // Zod strips unknown keys, so ListSkillsOutputSchema extracts only name/description
+        return types_1.ListSkillsOutputSchema.parse(data);
     }
-    async getByName(name) {
-        const params = { name };
-        const data = await this.requester.request('GET', '/agent_skills/by_name', {
-            params,
-        });
+    /**
+     * Get a skill by its ID.
+     *
+     * @param skillId - The UUID of the skill
+     * @returns Skill containing the full skill information including file_index
+     */
+    async get(skillId) {
+        const data = await this.requester.request('GET', `/agent_skills/${skillId}`);
         return types_1.SkillSchema.parse(data);
     }
     async delete(skillId) {
         await this.requester.request('DELETE', `/agent_skills/${skillId}`);
     }
-    async getFileByName(options) {
-        const endpoint = `/agent_skills/by_name/${options.skillName}/file`;
+    /**
+     * Get a file from a skill by skill ID.
+     *
+     * The backend automatically returns content for parseable text files, or a presigned URL
+     * for non-parseable files (binary, images, etc.).
+     *
+     * @param options - File retrieval options
+     * @param options.skillId - The UUID of the skill
+     * @param options.filePath - Relative path to the file within the skill (e.g., 'scripts/extract_text.json')
+     * @param options.expire - URL expiration time in seconds (defaults to 900 / 15 minutes)
+     * @returns GetSkillFileResp containing the file path, MIME type, and either content or URL
+     */
+    async getFile(options) {
+        const endpoint = `/agent_skills/${options.skillId}/file`;
         const params = {
             file_path: options.filePath,
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acontext/acontext",
-  "version": "0.0.19",
+  "version": "0.0.20",
   "description": "TypeScript SDK for the Acontext API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",