@acontext/acontext 0.0.19 → 0.0.21

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/sessions.d.ts

@@ -36,6 +36,17 @@ export declare class SessionsAPI {
         cursor?: string | null;
         timeDesc?: boolean | null;
     }): Promise<GetTasksOutput>;
+    /**
+     * Get a summary of all tasks in a session as a formatted string.
+     *
+     * @param sessionId - The UUID of the session.
+     * @param options - Options for retrieving the summary.
+     * @param options.limit - Maximum number of tasks to include in the summary.
+     * @returns A formatted string containing the session summary with all task information.
+     */
+    getSessionSummary(sessionId: string, options?: {
+        limit?: number | null;
+    }): Promise<string>;
     storeMessage(sessionId: string, blob: MessageBlob, options?: {
         format?: 'acontext' | 'openai' | 'anthropic' | 'gemini';
         fileField?: string | null;
@@ -54,6 +65,7 @@ export declare class SessionsAPI {
      * @param options.editStrategies - Optional list of edit strategies to apply before format conversion.
      *   Examples:
      *   - Remove tool results: [{ type: 'remove_tool_result', params: { keep_recent_n_tool_results: 3 } }]
+     *   - Middle out: [{ type: 'middle_out', params: { token_reduce_to: 5000 } }]
      *   - Token limit: [{ type: 'token_limit', params: { limit_tokens: 20000 } }]
      * @param options.pinEditingStrategiesAtMessage - Message ID to pin editing strategies at.
      *   When provided, strategies are only applied to messages up to and including this message ID,

package/dist/resources/sessions.js

@@ -79,6 +79,47 @@ class SessionsAPI {
         });
         return types_1.GetTasksOutputSchema.parse(data);
     }
+    /**
+     * Get a summary of all tasks in a session as a formatted string.
+     *
+     * @param sessionId - The UUID of the session.
+     * @param options - Options for retrieving the summary.
+     * @param options.limit - Maximum number of tasks to include in the summary.
+     * @returns A formatted string containing the session summary with all task information.
+     */
+    async getSessionSummary(sessionId, options) {
+        const tasksOutput = await this.getTasks(sessionId, {
+            limit: options?.limit,
+            timeDesc: false,
+        });
+        const tasks = tasksOutput.items;
+        if (tasks.length === 0) {
+            return '';
+        }
+        const parts = [];
+        for (const task of tasks) {
+            const taskLines = [
+                `<task id="${task.order}" description="${task.data.task_description}">`
+            ];
+            if (task.data.progresses && task.data.progresses.length > 0) {
+                taskLines.push('<progress>');
+                task.data.progresses.forEach((p, i) => {
+                    taskLines.push(`${i + 1}. ${p}`);
+                });
+                taskLines.push('</progress>');
+            }
+            if (task.data.user_preferences && task.data.user_preferences.length > 0) {
+                taskLines.push('<user_preference>');
+                task.data.user_preferences.forEach((pref, i) => {
+                    taskLines.push(`${i + 1}. ${pref}`);
+                });
+                taskLines.push('</user_preference>');
+            }
+            taskLines.push('</task>');
+            parts.push(taskLines.join('\n'));
+        }
+        return parts.join('\n');
+    }
     async storeMessage(sessionId, blob, options) {
         const format = options?.format ?? 'openai';
         if (!['acontext', 'openai', 'anthropic', 'gemini'].includes(format)) {
@@ -137,6 +178,7 @@ class SessionsAPI {
      * @param options.editStrategies - Optional list of edit strategies to apply before format conversion.
      *   Examples:
      *   - Remove tool results: [{ type: 'remove_tool_result', params: { keep_recent_n_tool_results: 3 } }]
+     *   - Middle out: [{ type: 'middle_out', params: { token_reduce_to: 5000 } }]
      *   - Token limit: [{ type: 'token_limit', params: { limit_tokens: 20000 } }]
      * @param options.pinEditingStrategiesAtMessage - Message ID to pin editing strategies at.
      *   When provided, strategies are only applied to messages up to and including this message ID,

package/dist/resources/skills.d.ts

@@ -23,16 +23,34 @@ export declare class SkillsAPI {
      * @returns ListSkillsOutput containing skills with name and description for the current page,
      *          along with pagination information (next_cursor and has_more)
      */
-    list_catalog(options?: {
+    listCatalog(options?: {
         user?: string | null;
         limit?: number | null;
         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");
@@ -41,13 +40,7 @@ class SkillsAPI {
      * @returns ListSkillsOutput containing skills with name and description for the current page,
      *          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(),
-        });
+    async listCatalog(options) {
         // 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/dist/types/session.d.ts

@@ -235,6 +235,25 @@ export declare const TokenLimitStrategySchema: z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type TokenLimitStrategy = z.infer<typeof TokenLimitStrategySchema>;
+/**
+ * Parameters for the middle_out edit strategy.
+ */
+export declare const MiddleOutParamsSchema: z.ZodObject<{
+    token_reduce_to: z.ZodNumber;
+}, z.core.$strip>;
+export type MiddleOutParams = z.infer<typeof MiddleOutParamsSchema>;
+/**
+ * Edit strategy to reduce prompt size by removing middle messages.
+ *
+ * Example: { type: 'middle_out', params: { token_reduce_to: 5000 } }
+ */
+export declare const MiddleOutStrategySchema: z.ZodObject<{
+    type: z.ZodLiteral<"middle_out">;
+    params: z.ZodObject<{
+        token_reduce_to: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type MiddleOutStrategy = z.infer<typeof MiddleOutStrategySchema>;
 /**
  * Union schema for all edit strategies.
  * When adding new strategies, extend this union: z.union([RemoveToolResultStrategySchema, OtherStrategySchema, ...])
@@ -257,5 +276,10 @@ export declare const EditStrategySchema: z.ZodUnion<readonly [z.ZodObject<{
     params: z.ZodObject<{
         limit_tokens: z.ZodNumber;
     }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"middle_out">;
+    params: z.ZodObject<{
+        token_reduce_to: z.ZodNumber;
+    }, z.core.$strip>;
 }, z.core.$strip>]>;
 export type EditStrategy = z.infer<typeof EditStrategySchema>;

package/dist/types/session.js

@@ -3,7 +3,7 @@
  * Type definitions for session, message, and task resources.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EditStrategySchema = exports.TokenLimitStrategySchema = exports.TokenLimitParamsSchema = exports.RemoveToolResultStrategySchema = exports.RemoveToolCallParamsStrategySchema = exports.RemoveToolCallParamsParamsSchema = exports.RemoveToolResultParamsSchema = exports.MessageObservingStatusSchema = exports.TokenCountsSchema = exports.LearningStatusSchema = exports.GetTasksOutputSchema = exports.GetMessagesOutputSchema = exports.PublicURLSchema = exports.ListSessionsOutputSchema = exports.TaskSchema = exports.TaskDataSchema = exports.SessionSchema = exports.MessageSchema = exports.PartSchema = exports.AssetSchema = void 0;
+exports.EditStrategySchema = exports.MiddleOutStrategySchema = exports.MiddleOutParamsSchema = exports.TokenLimitStrategySchema = exports.TokenLimitParamsSchema = exports.RemoveToolResultStrategySchema = exports.RemoveToolCallParamsStrategySchema = exports.RemoveToolCallParamsParamsSchema = exports.RemoveToolResultParamsSchema = exports.MessageObservingStatusSchema = exports.TokenCountsSchema = exports.LearningStatusSchema = exports.GetTasksOutputSchema = exports.GetMessagesOutputSchema = exports.PublicURLSchema = exports.ListSessionsOutputSchema = exports.TaskSchema = exports.TaskDataSchema = exports.SessionSchema = exports.MessageSchema = exports.PartSchema = exports.AssetSchema = void 0;
 const zod_1 = require("zod");
 exports.AssetSchema = zod_1.z.object({
     bucket: zod_1.z.string(),
@@ -190,6 +190,21 @@ exports.TokenLimitStrategySchema = zod_1.z.object({
     type: zod_1.z.literal('token_limit'),
     params: exports.TokenLimitParamsSchema,
 });
+/**
+ * Parameters for the middle_out edit strategy.
+ */
+exports.MiddleOutParamsSchema = zod_1.z.object({
+    token_reduce_to: zod_1.z.number(),
+});
+/**
+ * Edit strategy to reduce prompt size by removing middle messages.
+ *
+ * Example: { type: 'middle_out', params: { token_reduce_to: 5000 } }
+ */
+exports.MiddleOutStrategySchema = zod_1.z.object({
+    type: zod_1.z.literal('middle_out'),
+    params: exports.MiddleOutParamsSchema,
+});
 /**
  * Union schema for all edit strategies.
  * When adding new strategies, extend this union: z.union([RemoveToolResultStrategySchema, OtherStrategySchema, ...])
@@ -198,4 +213,5 @@ exports.EditStrategySchema = zod_1.z.union([
     exports.RemoveToolResultStrategySchema,
     exports.RemoveToolCallParamsStrategySchema,
     exports.TokenLimitStrategySchema,
+    exports.MiddleOutStrategySchema,
 ]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acontext/acontext",
-  "version": "0.0.19",
+  "version": "0.0.21",
   "description": "TypeScript SDK for the Acontext API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,6 +9,7 @@
     "dev": "tsc --watch",
     "test": "jest",
     "lint": "eslint src",
+    "e2e": "tsx examples/basic-usage.ts",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -35,6 +36,7 @@
     "eslint": "^9.39.1",
     "jest": "^30.2.0",
     "ts-jest": "^29.4.5",
+    "tsx": "^4.19.0",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {