@acontext/acontext 0.0.10 → 0.0.12

package/README.md

@@ -8,295 +8,6 @@ TypeScript SDK for interacting with the Acontext REST API.
 npm install @acontext/acontext
 ```
 
-## Quickstart
-
-```typescript
-import { AcontextClient, MessagePart } from '@acontext/acontext';
-
-const client = new AcontextClient({ apiKey: 'sk-ac-your-root-api-bearer-token' });
-
-// List spaces for the authenticated project
-const spaces = await client.spaces.list();
-
-// Create a session bound to the first space
-const session = await client.sessions.create({ spaceId: spaces.items[0].id });
-
-// Send a text message to the session
-await client.sessions.sendMessage(
-  session.id,
-  {
-    role: 'user',
-    parts: [MessagePart.textPart('Hello from TypeScript!')],
-  },
-  { format: 'acontext' }
-);
-
-// Flush session buffer when needed
-await client.sessions.flush(session.id);
-```
-
-See the inline documentation for the full list of helpers covering sessions, spaces, disks, and artifact uploads.
-
-## Health Check
-
-Test connectivity to the Acontext API server:
-
-```typescript
-import { AcontextClient } from '@acontext/acontext';
-
-const client = new AcontextClient({ apiKey: 'sk-ac-your-root-api-bearer-token' });
-
-// Ping the server
-const pong = await client.ping();
-console.log(`Server responded: ${pong}`); // Output: Server responded: pong
-```
-
-This is useful for:
-- Verifying API connectivity before performing operations
-- Health checks in monitoring systems
-- Debugging connection issues
-
-## Managing disks and artifacts
-
-Artifacts now live under project disks. Create a disk first, then upload files through the disk-scoped helper:
-
-```typescript
-import { AcontextClient, FileUpload } from '@acontext/acontext';
-
-const client = new AcontextClient({ apiKey: 'sk-ac-your-root-api-bearer-token' });
-
-const disk = await client.disks.create();
-await client.disks.artifacts.upsert(
-  disk.id,
-  {
-    file: new FileUpload({
-      filename: 'retro_notes.md',
-      content: Buffer.from('# Retro Notes\nWe shipped file uploads successfully!\n'),
-      contentType: 'text/markdown',
-    }),
-    filePath: '/notes/',
-    meta: { source: 'readme-demo' },
-  }
-);
-```
-
-## Working with blocks
-
-```typescript
-import { AcontextClient } from '@acontext/acontext';
-
-const client = new AcontextClient({ apiKey: 'sk-ac-your-root-api-bearer-token' });
-
-const space = await client.spaces.create();
-const page = await client.blocks.create(space.id, {
-  blockType: 'page',
-  title: 'Kick-off Notes',
-});
-await client.blocks.create(space.id, {
-  parentId: page.id,
-  blockType: 'text',
-  title: 'First block',
-  props: { text: 'Plan the sprint goals' },
-});
-```
-
-## Managing sessions
-
-### Flush session buffer
-
-The `flush` method clears the session buffer, useful for managing session state:
-
-```typescript
-const result = await client.sessions.flush('session-uuid');
-console.log(result); // { status: 0, errmsg: '' }
-```
-
-## Working with tools
-
-The SDK provides APIs to manage tool names within your project:
-
-### Get tool names
-
-```typescript
-const tools = await client.tools.getToolName();
-for (const tool of tools) {
-  console.log(`${tool.name} (used in ${tool.sop_count} SOPs)`);
-}
-```
-
-### Rename tool names
-
-```typescript
-const result = await client.tools.renameToolName({
-  rename: [
-    { oldName: 'calculate', newName: 'calculate_math' },
-    { oldName: 'search', newName: 'search_web' },
-  ],
-});
-console.log(result); // { status: 0, errmsg: '' }
-```
-
-## Agent Tools
-
-The SDK provides agent tools that allow LLMs (OpenAI, Anthropic) to interact with Acontext disks through function calling. These tools can be converted to OpenAI or Anthropic tool schemas and executed when the LLM calls them.
-
-### Pre-configured Disk Tools
-
-The SDK includes a pre-configured `DISK_TOOLS` pool with four disk operation tools:
-
-- **`write_file`**: Write text content to a file
-- **`read_file`**: Read a text file with optional line offset and limit
-- **`replace_string`**: Replace strings in a file
-- **`list_artifacts`**: List files and directories in a path
-
-### Getting Tool Schemas for LLM APIs
-
-Convert tools to the appropriate format for your LLM provider:
-
-```typescript
-import { AcontextClient, DISK_TOOLS } from '@acontext/acontext';
-
-const client = new AcontextClient({ apiKey: 'sk-ac-your-root-api-bearer-token' });
-
-// Get OpenAI-compatible tool schemas
-const openaiTools = DISK_TOOLS.toOpenAIToolSchema();
-
-// Get Anthropic-compatible tool schemas
-const anthropicTools = DISK_TOOLS.toAnthropicToolSchema();
-
-// Use with OpenAI API
-import OpenAI from 'openai';
-const openai = new OpenAI({ apiKey: 'your-openai-key' });
-const completion = await openai.chat.completions.create({
-  model: 'gpt-4',
-  messages: [{ role: 'user', content: 'Write a file called hello.txt with "Hello, World!"' }],
-  tools: openaiTools,
-});
-```
-
-### Executing Tools
-
-When an LLM calls a tool, execute it using the tool pool:
-
-```typescript
-import { AcontextClient, DISK_TOOLS } from '@acontext/acontext';
-
-const client = new AcontextClient({ apiKey: 'sk-ac-your-root-api-bearer-token' });
-
-// Create a disk for the tools to operate on
-const disk = await client.disks.create();
-
-// Create a context for the tools
-const ctx = DISK_TOOLS.formatContext(client, disk.id);
-
-// Execute a tool (e.g., after LLM returns a tool call)
-const result = await DISK_TOOLS.executeTool(ctx, 'write_file', {
-  filename: 'hello.txt',
-  file_path: '/notes/',
-  content: 'Hello, World!',
-});
-console.log(result); // File 'hello.txt' written successfully to '/notes/hello.txt'
-
-// Read the file
-const readResult = await DISK_TOOLS.executeTool(ctx, 'read_file', {
-  filename: 'hello.txt',
-  file_path: '/notes/',
-});
-console.log(readResult);
-
-// List files in a directory
-const listResult = await DISK_TOOLS.executeTool(ctx, 'list_artifacts', {
-  file_path: '/notes/',
-});
-console.log(listResult);
-
-// Replace a string in a file
-const replaceResult = await DISK_TOOLS.executeTool(ctx, 'replace_string', {
-  filename: 'hello.txt',
-  file_path: '/notes/',
-  old_string: 'Hello',
-  new_string: 'Hi',
-});
-console.log(replaceResult);
-```
-
-### Creating Custom Tools
-
-You can create custom tools by extending `AbstractBaseTool`:
-
-```typescript
-import { AbstractBaseTool, BaseContext, BaseToolPool } from '@acontext/acontext';
-
-interface MyContext extends BaseContext {
-  // Your context properties
-}
-
-class MyCustomTool extends AbstractBaseTool {
-  readonly name = 'my_custom_tool';
-  readonly description = 'A custom tool that does something';
-  readonly arguments = {
-    param1: {
-      type: 'string',
-      description: 'First parameter',
-    },
-  };
-  readonly requiredArguments = ['param1'];
-
-  async execute(ctx: MyContext, llmArguments: Record<string, unknown>): Promise<string> {
-    const param1 = llmArguments.param1 as string;
-    // Your custom logic here
-    return `Result: ${param1}`;
-  }
-}
-
-// Create a custom tool pool
-class MyToolPool extends BaseToolPool {
-  formatContext(...args: unknown[]): MyContext {
-    // Create and return your context
-    return {};
-  }
-}
-
-const myPool = new MyToolPool();
-myPool.addTool(new MyCustomTool());
-```
-
-## Semantic search within spaces
-
-The SDK provides a powerful semantic search API for finding content within your spaces:
-
-### 1. Experience Search (Advanced AI-powered search)
-
-The most sophisticated search that can operate in two modes: **fast** (quick semantic search) or **agentic** (AI-powered iterative refinement).
-
-```typescript
-import { AcontextClient } from '@acontext/acontext';
-
-const client = new AcontextClient({ apiKey: 'sk_project_token' });
-
-// Fast mode - quick semantic search
-const result = await client.spaces.experienceSearch('space-uuid', {
-  query: 'How to implement authentication?',
-  limit: 10,
-  mode: 'fast',
-  semanticThreshold: 0.8,
-});
-
-// Agentic mode - AI-powered iterative search
-const agenticResult = await client.spaces.experienceSearch('space-uuid', {
-  query: 'What are the best practices for API security?',
-  limit: 10,
-  mode: 'agentic',
-  maxIterations: 20,
-});
-
-// Access results
-for (const block of result.cited_blocks) {
-  console.log(`${block.title} (distance: ${block.distance})`);
-}
-
-if (result.final_answer) {
-  console.log(`AI Answer: ${result.final_answer}`);
-}
-```
+# 🔍 Document
 
+To understand more about this SDK, please view [our docs](https://docs.acontext.io/) and [api references](https://docs.acontext.io/api-reference/introduction)

package/dist/resources/sessions.d.ts

@@ -34,7 +34,7 @@ export declare class SessionsAPI {
         cursor?: string | null;
         timeDesc?: boolean | null;
     }): Promise<GetTasksOutput>;
-    sendMessage(sessionId: string, blob: MessageBlob, options?: {
+    storeMessage(sessionId: string, blob: MessageBlob, options?: {
         format?: 'acontext' | 'openai' | 'anthropic';
         fileField?: string | null;
         file?: FileUpload | null;

package/dist/resources/sessions.js

@@ -73,7 +73,7 @@ class SessionsAPI {
         });
         return types_1.GetTasksOutputSchema.parse(data);
     }
-    async sendMessage(sessionId, blob, options) {
+    async storeMessage(sessionId, blob, options) {
         const format = options?.format ?? 'openai';
         if (!['acontext', 'openai', 'anthropic'].includes(format)) {
             throw new Error("format must be one of {'acontext', 'openai', 'anthropic'}");

package/dist/types/session.d.ts

@@ -62,12 +62,29 @@ export declare const SessionSchema: z.ZodObject<{
     updated_at: z.ZodString;
 }, z.core.$strip>;
 export type Session = z.infer<typeof SessionSchema>;
+/**
+ * TaskData represents the structured data stored in a task.
+ * This schema matches the TaskData model in acontext_core/schema/session/task.py
+ * and the Go API TaskData struct.
+ */
+export declare const TaskDataSchema: z.ZodObject<{
+    task_description: z.ZodString;
+    progresses: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    user_preferences: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    sop_thinking: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type TaskData = z.infer<typeof TaskDataSchema>;
 export declare const TaskSchema: z.ZodObject<{
     id: z.ZodString;
     session_id: z.ZodString;
     project_id: z.ZodString;
     order: z.ZodNumber;
-    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    data: z.ZodObject<{
+        task_description: z.ZodString;
+        progresses: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+        user_preferences: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+        sop_thinking: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>;
     status: z.ZodString;
     is_planning: z.ZodBoolean;
     space_digested: z.ZodBoolean;
@@ -96,6 +113,7 @@ export declare const PublicURLSchema: z.ZodObject<{
 export type PublicURL = z.infer<typeof PublicURLSchema>;
 export declare const GetMessagesOutputSchema: z.ZodObject<{
     items: z.ZodArray<z.ZodUnknown>;
+    ids: z.ZodArray<z.ZodString>;
     next_cursor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     has_more: z.ZodBoolean;
     public_urls: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -110,7 +128,12 @@ export declare const GetTasksOutputSchema: z.ZodObject<{
         session_id: z.ZodString;
         project_id: z.ZodString;
         order: z.ZodNumber;
-        data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        data: z.ZodObject<{
+            task_description: z.ZodString;
+            progresses: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+            user_preferences: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+            sop_thinking: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>;
         status: z.ZodString;
         is_planning: z.ZodBoolean;
         space_digested: z.ZodBoolean;
@@ -138,6 +161,29 @@ export declare const RemoveToolResultParamsSchema: z.ZodObject<{
     tool_result_placeholder: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type RemoveToolResultParams = z.infer<typeof RemoveToolResultParamsSchema>;
+/**
+ * Parameters for the remove_tool_call_params edit strategy.
+ */
+export declare const RemoveToolCallParamsParamsSchema: z.ZodObject<{
+    keep_recent_n_tool_calls: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type RemoveToolCallParamsParams = z.infer<typeof RemoveToolCallParamsParamsSchema>;
+/**
+ * Edit strategy to remove parameters from old tool-call parts.
+ *
+ * Keeps the most recent N tool calls with full parameters, replacing older
+ * tool call arguments with empty JSON "{}". The tool call ID and name remain
+ * intact so tool-results can still reference them.
+ *
+ * Example: { type: 'remove_tool_call_params', params: { keep_recent_n_tool_calls: 5 } }
+ */
+export declare const RemoveToolCallParamsStrategySchema: z.ZodObject<{
+    type: z.ZodLiteral<"remove_tool_call_params">;
+    params: z.ZodObject<{
+        keep_recent_n_tool_calls: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type RemoveToolCallParamsStrategy = z.infer<typeof RemoveToolCallParamsStrategySchema>;
 /**
  * Edit strategy to replace old tool results with placeholder text.
  *
@@ -184,6 +230,11 @@ export declare const EditStrategySchema: z.ZodUnion<readonly [z.ZodObject<{
         keep_recent_n_tool_results: z.ZodOptional<z.ZodNumber>;
         tool_result_placeholder: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"remove_tool_call_params">;
+    params: z.ZodObject<{
+        keep_recent_n_tool_calls: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"token_limit">;
     params: z.ZodObject<{

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.RemoveToolResultParamsSchema = exports.TokenCountsSchema = exports.LearningStatusSchema = exports.GetTasksOutputSchema = exports.GetMessagesOutputSchema = exports.PublicURLSchema = exports.ListSessionsOutputSchema = exports.TaskSchema = exports.SessionSchema = exports.MessageSchema = exports.PartSchema = exports.AssetSchema = void 0;
+exports.EditStrategySchema = exports.TokenLimitStrategySchema = exports.TokenLimitParamsSchema = exports.RemoveToolResultStrategySchema = exports.RemoveToolCallParamsStrategySchema = exports.RemoveToolCallParamsParamsSchema = exports.RemoveToolResultParamsSchema = 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(),
@@ -41,12 +41,23 @@ exports.SessionSchema = zod_1.z.object({
     created_at: zod_1.z.string(),
     updated_at: zod_1.z.string(),
 });
+/**
+ * TaskData represents the structured data stored in a task.
+ * This schema matches the TaskData model in acontext_core/schema/session/task.py
+ * and the Go API TaskData struct.
+ */
+exports.TaskDataSchema = zod_1.z.object({
+    task_description: zod_1.z.string(),
+    progresses: zod_1.z.array(zod_1.z.string()).nullable().optional(),
+    user_preferences: zod_1.z.array(zod_1.z.string()).nullable().optional(),
+    sop_thinking: zod_1.z.string().nullable().optional(),
+});
 exports.TaskSchema = zod_1.z.object({
     id: zod_1.z.string(),
     session_id: zod_1.z.string(),
     project_id: zod_1.z.string(),
     order: zod_1.z.number(),
-    data: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+    data: exports.TaskDataSchema,
     status: zod_1.z.string(),
     is_planning: zod_1.z.boolean(),
     space_digested: zod_1.z.boolean(),
@@ -64,6 +75,7 @@ exports.PublicURLSchema = zod_1.z.object({
 });
 exports.GetMessagesOutputSchema = zod_1.z.object({
     items: zod_1.z.array(zod_1.z.unknown()),
+    ids: zod_1.z.array(zod_1.z.string()),
     next_cursor: zod_1.z.string().nullable().optional(),
     has_more: zod_1.z.boolean(),
     public_urls: zod_1.z.record(zod_1.z.string(), exports.PublicURLSchema).nullable().optional(),
@@ -95,6 +107,29 @@ exports.RemoveToolResultParamsSchema = zod_1.z.object({
      */
     tool_result_placeholder: zod_1.z.string().optional(),
 });
+/**
+ * Parameters for the remove_tool_call_params edit strategy.
+ */
+exports.RemoveToolCallParamsParamsSchema = zod_1.z.object({
+    /**
+     * Number of most recent tool calls to keep with full parameters.
+     * @default 3
+     */
+    keep_recent_n_tool_calls: zod_1.z.number().optional(),
+});
+/**
+ * Edit strategy to remove parameters from old tool-call parts.
+ *
+ * Keeps the most recent N tool calls with full parameters, replacing older
+ * tool call arguments with empty JSON "{}". The tool call ID and name remain
+ * intact so tool-results can still reference them.
+ *
+ * Example: { type: 'remove_tool_call_params', params: { keep_recent_n_tool_calls: 5 } }
+ */
+exports.RemoveToolCallParamsStrategySchema = zod_1.z.object({
+    type: zod_1.z.literal('remove_tool_call_params'),
+    params: exports.RemoveToolCallParamsParamsSchema,
+});
 /**
  * Edit strategy to replace old tool results with placeholder text.
  *
@@ -134,5 +169,6 @@ exports.TokenLimitStrategySchema = zod_1.z.object({
  */
 exports.EditStrategySchema = zod_1.z.union([
     exports.RemoveToolResultStrategySchema,
+    exports.RemoveToolCallParamsStrategySchema,
     exports.TokenLimitStrategySchema,
 ]);

package/package.json

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