@axiom-lattice/core 2.1.22 → 2.1.24
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.mts +1641 -68
- package/dist/index.d.ts +1641 -68
- package/dist/index.js +3796 -495
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +3755 -495
- package/dist/index.mjs.map +1 -1
- package/package.json +2 -2
package/dist/index.d.mts
CHANGED
|
@@ -2,21 +2,21 @@ import { BaseMessage } from '@langchain/core/messages';
|
|
|
2
2
|
import { ZodType } from 'zod/v3';
|
|
3
3
|
import { $ZodType } from 'zod/v4/core';
|
|
4
4
|
import { BaseChatModel, BaseChatModelCallOptions } from '@langchain/core/language_models/chat_models';
|
|
5
|
-
import { BaseLanguageModelInput } from '@langchain/core/language_models/base';
|
|
5
|
+
import { BaseLanguageModelInput, LanguageModelLike } from '@langchain/core/language_models/base';
|
|
6
6
|
import { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
|
|
7
7
|
import { ChatResult } from '@langchain/core/outputs';
|
|
8
|
-
import
|
|
9
|
-
import
|
|
10
|
-
export {
|
|
8
|
+
import * as _axiom_lattice_protocols from '@axiom-lattice/protocols';
|
|
9
|
+
import { LLMConfig, ToolConfig, ToolExecutor, AgentConfig, MiddlewareType, GraphBuildOptions, MessageChunk, QueueLatticeProtocol, QueueConfig, QueueClient, QueueResult, ScheduleLatticeProtocol, ScheduleConfig, ScheduleClient, ScheduleStorage, TaskHandler, ScheduleOnceOptions, ScheduleCronOptions, ScheduledTaskDefinition, ScheduledTaskStatus, ScheduleExecutionType, ThreadStore, AssistantStore, SkillStore, WorkspaceStore, ProjectStore, DatabaseConfigStore, Thread, CreateThreadRequest, Assistant, CreateAssistantRequest, Skill, CreateSkillRequest, DatabaseConfigEntry, CreateDatabaseConfigRequest, UpdateDatabaseConfigRequest, LoggerLatticeProtocol, LoggerConfig, LoggerClient, LoggerContext, SkillConfig, SkillClient } from '@axiom-lattice/protocols';
|
|
10
|
+
export { _axiom_lattice_protocols as Protocols };
|
|
11
11
|
export { AgentConfig, AgentType, GraphBuildOptions, MemoryType } from '@axiom-lattice/protocols';
|
|
12
12
|
import * as langchain from 'langchain';
|
|
13
|
-
import { ReactAgent } from 'langchain';
|
|
14
|
-
import z from 'zod';
|
|
13
|
+
import { ReactAgent, AgentMiddleware } from 'langchain';
|
|
14
|
+
import z, { z as z$1 } from 'zod';
|
|
15
15
|
import { SandboxClient } from '@agent-infra/sandbox';
|
|
16
16
|
import * as _langchain_core_tools from '@langchain/core/tools';
|
|
17
17
|
import { StructuredTool } from '@langchain/core/tools';
|
|
18
18
|
import { CompiledStateGraph } from '@langchain/langgraph';
|
|
19
|
-
import { BaseCheckpointSaver } from '@langchain/langgraph-checkpoint';
|
|
19
|
+
import { BaseCheckpointSaver, BaseStore } from '@langchain/langgraph-checkpoint';
|
|
20
20
|
import { ReplaySubject } from 'rxjs';
|
|
21
21
|
import { Embeddings } from '@langchain/core/embeddings';
|
|
22
22
|
import { VectorStore } from '@langchain/core/vectorstores';
|
|
@@ -300,11 +300,6 @@ interface ISqlDatabase {
|
|
|
300
300
|
getDatabaseType(): DatabaseType;
|
|
301
301
|
}
|
|
302
302
|
|
|
303
|
-
/**
|
|
304
|
-
* SQL Database Manager
|
|
305
|
-
* Singleton manager for SQL database connections
|
|
306
|
-
*/
|
|
307
|
-
|
|
308
303
|
/**
|
|
309
304
|
* PostgreSQL Database Implementation
|
|
310
305
|
* Uses pg library for PostgreSQL connections
|
|
@@ -369,58 +364,101 @@ declare class SqlDatabaseManager {
|
|
|
369
364
|
* Disconnect all databases
|
|
370
365
|
*/
|
|
371
366
|
disconnectAll(): Promise<void>;
|
|
367
|
+
/**
|
|
368
|
+
* Load database configurations from a DatabaseConfigStore
|
|
369
|
+
* and register them with this manager
|
|
370
|
+
*
|
|
371
|
+
* @param store - The database configuration store
|
|
372
|
+
* @param tenantId - Tenant identifier
|
|
373
|
+
*/
|
|
374
|
+
loadConfigsFromStore(store: _axiom_lattice_protocols.DatabaseConfigStore, tenantId: string): Promise<void>;
|
|
375
|
+
/**
|
|
376
|
+
* Load all database configurations from a DatabaseConfigStore
|
|
377
|
+
* across all tenants and register them with this manager
|
|
378
|
+
*
|
|
379
|
+
* @param store - The database configuration store
|
|
380
|
+
*/
|
|
381
|
+
loadAllConfigsFromStore(store: _axiom_lattice_protocols.DatabaseConfigStore): Promise<void>;
|
|
372
382
|
}
|
|
373
383
|
declare const sqlDatabaseManager: SqlDatabaseManager;
|
|
374
384
|
|
|
375
|
-
interface CreateSqlToolParams {
|
|
376
|
-
|
|
377
|
-
|
|
385
|
+
interface CreateSqlToolParams$3 {
|
|
386
|
+
databaseKeys: string[];
|
|
387
|
+
databaseDescriptions?: Record<string, string>;
|
|
378
388
|
}
|
|
379
|
-
declare const createListTablesSqlTool: ({
|
|
389
|
+
declare const createListTablesSqlTool: ({ databaseKeys, databaseDescriptions }: CreateSqlToolParams$3) => langchain.DynamicStructuredTool<z.ZodObject<{
|
|
390
|
+
databaseKey: z.ZodString;
|
|
391
|
+
}, "strip", z.ZodTypeAny, {
|
|
392
|
+
databaseKey: string;
|
|
393
|
+
}, {
|
|
394
|
+
databaseKey: string;
|
|
395
|
+
}>, {
|
|
396
|
+
databaseKey: string;
|
|
397
|
+
}, {
|
|
398
|
+
databaseKey: string;
|
|
399
|
+
}, string>;
|
|
380
400
|
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
}
|
|
401
|
+
interface CreateSqlToolParams$2 {
|
|
402
|
+
databaseKeys: string[];
|
|
403
|
+
databaseDescriptions?: Record<string, string>;
|
|
404
|
+
}
|
|
405
|
+
declare const createInfoSqlTool: ({ databaseKeys, databaseDescriptions }: CreateSqlToolParams$2) => langchain.DynamicStructuredTool<z.ZodObject<{
|
|
385
406
|
tables: z.ZodString;
|
|
407
|
+
databaseKey: z.ZodString;
|
|
386
408
|
}, "strip", z.ZodTypeAny, {
|
|
409
|
+
databaseKey: string;
|
|
387
410
|
tables: string;
|
|
388
411
|
}, {
|
|
412
|
+
databaseKey: string;
|
|
389
413
|
tables: string;
|
|
390
414
|
}>, {
|
|
391
415
|
tables: string;
|
|
416
|
+
databaseKey: string;
|
|
392
417
|
}, {
|
|
418
|
+
databaseKey: string;
|
|
393
419
|
tables: string;
|
|
394
420
|
}, string>;
|
|
395
421
|
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
}
|
|
422
|
+
interface CreateSqlToolParams$1 {
|
|
423
|
+
databaseKeys: string[];
|
|
424
|
+
databaseDescriptions?: Record<string, string>;
|
|
425
|
+
}
|
|
426
|
+
declare const createQueryCheckerSqlTool: ({ databaseKeys, databaseDescriptions }: CreateSqlToolParams$1) => langchain.DynamicStructuredTool<z.ZodObject<{
|
|
400
427
|
query: z.ZodString;
|
|
428
|
+
databaseKey: z.ZodString;
|
|
401
429
|
}, "strip", z.ZodTypeAny, {
|
|
402
430
|
query: string;
|
|
431
|
+
databaseKey: string;
|
|
403
432
|
}, {
|
|
404
433
|
query: string;
|
|
434
|
+
databaseKey: string;
|
|
405
435
|
}>, {
|
|
406
436
|
query: string;
|
|
437
|
+
databaseKey: string;
|
|
407
438
|
}, {
|
|
408
439
|
query: string;
|
|
440
|
+
databaseKey: string;
|
|
409
441
|
}, string>;
|
|
410
442
|
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
}
|
|
443
|
+
interface CreateSqlToolParams {
|
|
444
|
+
databaseKeys: string[];
|
|
445
|
+
databaseDescriptions?: Record<string, string>;
|
|
446
|
+
}
|
|
447
|
+
declare const createQuerySqlTool: ({ databaseKeys, databaseDescriptions }: CreateSqlToolParams) => langchain.DynamicStructuredTool<z.ZodObject<{
|
|
415
448
|
query: z.ZodString;
|
|
449
|
+
databaseKey: z.ZodString;
|
|
416
450
|
}, "strip", z.ZodTypeAny, {
|
|
417
451
|
query: string;
|
|
452
|
+
databaseKey: string;
|
|
418
453
|
}, {
|
|
419
454
|
query: string;
|
|
455
|
+
databaseKey: string;
|
|
420
456
|
}>, {
|
|
421
457
|
query: string;
|
|
458
|
+
databaseKey: string;
|
|
422
459
|
}, {
|
|
423
460
|
query: string;
|
|
461
|
+
databaseKey: string;
|
|
424
462
|
}, string>;
|
|
425
463
|
|
|
426
464
|
interface SandboxManagerProtocol {
|
|
@@ -544,6 +582,31 @@ interface AgentLattice {
|
|
|
544
582
|
config: AgentConfig;
|
|
545
583
|
client?: AgentClient | undefined;
|
|
546
584
|
}
|
|
585
|
+
interface MiddlewareConfig {
|
|
586
|
+
id: string;
|
|
587
|
+
type: MiddlewareType;
|
|
588
|
+
name: string;
|
|
589
|
+
description: string;
|
|
590
|
+
enabled: boolean;
|
|
591
|
+
config: Record<string, any>;
|
|
592
|
+
}
|
|
593
|
+
interface AgentBuildParams {
|
|
594
|
+
middleware?: MiddlewareConfig[];
|
|
595
|
+
skillCategories?: string[];
|
|
596
|
+
tools: Array<{
|
|
597
|
+
key: string;
|
|
598
|
+
definition: any;
|
|
599
|
+
executor: any;
|
|
600
|
+
}>;
|
|
601
|
+
model: ModelLattice;
|
|
602
|
+
subAgents: Array<{
|
|
603
|
+
key: string;
|
|
604
|
+
config: AgentConfig;
|
|
605
|
+
client: AgentClient | undefined;
|
|
606
|
+
}>;
|
|
607
|
+
prompt: string;
|
|
608
|
+
stateSchema?: z$1.ZodObject<any, any, any, any, any>;
|
|
609
|
+
}
|
|
547
610
|
|
|
548
611
|
/**
|
|
549
612
|
* AgentLatticeManager - 单例Agent Lattice管理器
|
|
@@ -570,6 +633,19 @@ declare class AgentLatticeManager extends BaseLatticeManager<AgentLattice> {
|
|
|
570
633
|
* @param config Agent配置
|
|
571
634
|
*/
|
|
572
635
|
registerLattice(config: AgentConfig): void;
|
|
636
|
+
/**
|
|
637
|
+
* Register a pre-built teammate agent client for dynamic team spawning.
|
|
638
|
+
* Used when spawning teammates via agentWorkerGraph - the agent must exist
|
|
639
|
+
* in the lattice before the worker invokes it.
|
|
640
|
+
*
|
|
641
|
+
* @param key Unique key (e.g. `team:${teamId}:${agentName}`)
|
|
642
|
+
* @param client Pre-built AgentClient (ReactAgent or CompiledGraph)
|
|
643
|
+
*/
|
|
644
|
+
registerTeammateAgent(key: string, client: AgentClient): void;
|
|
645
|
+
/**
|
|
646
|
+
* Unregister a teammate agent. Call when a team is done to clean up.
|
|
647
|
+
*/
|
|
648
|
+
unregisterTeammateAgent(key: string): boolean;
|
|
573
649
|
/**
|
|
574
650
|
* 获取AgentLattice
|
|
575
651
|
* @param key Lattice键名
|
|
@@ -651,6 +727,8 @@ declare const getAgentLattice: (key: string) => AgentLattice | undefined;
|
|
|
651
727
|
declare const getAgentConfig: (key: string) => AgentConfig | undefined;
|
|
652
728
|
declare const getAllAgentConfigs: () => Promise<AgentConfig[]>;
|
|
653
729
|
declare const validateAgentInput: (key: string, input: any) => boolean;
|
|
730
|
+
declare const registerTeammateAgent: (key: string, client: AgentClient) => void;
|
|
731
|
+
declare const unregisterTeammateAgent: (key: string) => boolean;
|
|
654
732
|
/**
|
|
655
733
|
* 获取或初始化Agent客户端
|
|
656
734
|
*
|
|
@@ -1277,6 +1355,9 @@ type StoreTypeMap = {
|
|
|
1277
1355
|
thread: ThreadStore;
|
|
1278
1356
|
assistant: AssistantStore;
|
|
1279
1357
|
skill: SkillStore;
|
|
1358
|
+
workspace: WorkspaceStore;
|
|
1359
|
+
project: ProjectStore;
|
|
1360
|
+
database: DatabaseConfigStore;
|
|
1280
1361
|
};
|
|
1281
1362
|
/**
|
|
1282
1363
|
* Store type keys
|
|
@@ -1552,6 +1633,67 @@ declare class FileSystemSkillStore implements SkillStore {
|
|
|
1552
1633
|
getSubSkills(parentSkillName: string): Promise<Skill[]>;
|
|
1553
1634
|
}
|
|
1554
1635
|
|
|
1636
|
+
/**
|
|
1637
|
+
* InMemoryDatabaseConfigStore
|
|
1638
|
+
*
|
|
1639
|
+
* In-memory implementation of DatabaseConfigStore
|
|
1640
|
+
* Provides CRUD operations for database configuration data stored in memory
|
|
1641
|
+
*
|
|
1642
|
+
* Note: This implementation does NOT encrypt passwords - use with caution
|
|
1643
|
+
* For production use, prefer PostgreSQLDatabaseConfigStore
|
|
1644
|
+
*/
|
|
1645
|
+
|
|
1646
|
+
/**
|
|
1647
|
+
* In-memory implementation of DatabaseConfigStore
|
|
1648
|
+
*/
|
|
1649
|
+
declare class InMemoryDatabaseConfigStore implements DatabaseConfigStore {
|
|
1650
|
+
private configs;
|
|
1651
|
+
/**
|
|
1652
|
+
* Get composite key for storage
|
|
1653
|
+
*/
|
|
1654
|
+
private getKey;
|
|
1655
|
+
/**
|
|
1656
|
+
* Get all database configurations for a tenant
|
|
1657
|
+
*/
|
|
1658
|
+
getAllConfigs(tenantId: string): Promise<DatabaseConfigEntry[]>;
|
|
1659
|
+
/**
|
|
1660
|
+
* Get all database configurations across all tenants
|
|
1661
|
+
*/
|
|
1662
|
+
getAllConfigsWithoutTenant(): Promise<DatabaseConfigEntry[]>;
|
|
1663
|
+
/**
|
|
1664
|
+
* Get database configuration by ID
|
|
1665
|
+
*/
|
|
1666
|
+
getConfigById(tenantId: string, id: string): Promise<DatabaseConfigEntry | null>;
|
|
1667
|
+
/**
|
|
1668
|
+
* Get database configuration by business key
|
|
1669
|
+
*/
|
|
1670
|
+
getConfigByKey(tenantId: string, key: string): Promise<DatabaseConfigEntry | null>;
|
|
1671
|
+
/**
|
|
1672
|
+
* Create a new database configuration
|
|
1673
|
+
*/
|
|
1674
|
+
createConfig(tenantId: string, id: string, data: CreateDatabaseConfigRequest): Promise<DatabaseConfigEntry>;
|
|
1675
|
+
/**
|
|
1676
|
+
* Update an existing database configuration
|
|
1677
|
+
*/
|
|
1678
|
+
updateConfig(tenantId: string, id: string, updates: Partial<UpdateDatabaseConfigRequest>): Promise<DatabaseConfigEntry | null>;
|
|
1679
|
+
/**
|
|
1680
|
+
* Delete a database configuration by ID
|
|
1681
|
+
*/
|
|
1682
|
+
deleteConfig(tenantId: string, id: string): Promise<boolean>;
|
|
1683
|
+
/**
|
|
1684
|
+
* Check if configuration exists
|
|
1685
|
+
*/
|
|
1686
|
+
hasConfig(tenantId: string, id: string): Promise<boolean>;
|
|
1687
|
+
/**
|
|
1688
|
+
* Clear all configurations (useful for testing)
|
|
1689
|
+
*/
|
|
1690
|
+
clear(): void;
|
|
1691
|
+
/**
|
|
1692
|
+
* Clear configurations for a specific tenant
|
|
1693
|
+
*/
|
|
1694
|
+
clearByTenant(tenantId: string): void;
|
|
1695
|
+
}
|
|
1696
|
+
|
|
1555
1697
|
/**
|
|
1556
1698
|
* Embeddings Lattice Interface
|
|
1557
1699
|
* Defines the structure of an embeddings lattice entry
|
|
@@ -2107,60 +2249,1491 @@ declare function normalizeSandboxName(name: string): string;
|
|
|
2107
2249
|
declare function isValidSandboxName(name: string): boolean;
|
|
2108
2250
|
|
|
2109
2251
|
/**
|
|
2110
|
-
*
|
|
2111
|
-
*
|
|
2252
|
+
* Agent Team - Store Protocols
|
|
2253
|
+
*
|
|
2254
|
+
* Defines the TaskListStore and MailboxStore interfaces.
|
|
2255
|
+
* These are external shared stores (not agent internal state), following the
|
|
2256
|
+
* same Protocol -> Implementation pattern as ThreadStore / InMemoryThreadStore.
|
|
2257
|
+
*
|
|
2258
|
+
* All methods are scoped by `teamId` so a single store instance can serve
|
|
2259
|
+
* multiple concurrent teams (like ThreadStore is scoped by assistantId).
|
|
2112
2260
|
*/
|
|
2113
|
-
|
|
2114
|
-
|
|
2115
|
-
|
|
2116
|
-
|
|
2261
|
+
|
|
2262
|
+
/**
|
|
2263
|
+
* External shared storage for team tasks.
|
|
2264
|
+
*
|
|
2265
|
+
* Leader and teammates access the same store instance to add, claim,
|
|
2266
|
+
* complete, and query tasks. Implementations can be in-memory, filesystem,
|
|
2267
|
+
* database, etc.
|
|
2268
|
+
*/
|
|
2269
|
+
interface TaskListStore {
|
|
2117
2270
|
/**
|
|
2118
|
-
*
|
|
2119
|
-
* @
|
|
2271
|
+
* Add a single task to the team's task list.
|
|
2272
|
+
* @returns The created task with generated id and timestamps.
|
|
2120
2273
|
*/
|
|
2121
|
-
|
|
2274
|
+
addTask(teamId: string, spec: TaskSpec): Promise<TeamTask>;
|
|
2122
2275
|
/**
|
|
2123
|
-
*
|
|
2124
|
-
*
|
|
2125
|
-
* @param data Event data
|
|
2126
|
-
* @param useQueue Whether to use queue for publishing
|
|
2276
|
+
* Add multiple tasks at once. Dependency references (by title) are
|
|
2277
|
+
* resolved to task IDs within this batch + existing tasks.
|
|
2127
2278
|
*/
|
|
2128
|
-
|
|
2279
|
+
addTasks(teamId: string, specs: TaskSpec[]): Promise<TeamTask[]>;
|
|
2129
2280
|
/**
|
|
2130
|
-
*
|
|
2131
|
-
* @
|
|
2132
|
-
* @param callback Callback function
|
|
2281
|
+
* Update mutable fields of an existing task.
|
|
2282
|
+
* @returns The updated task, or null if not found.
|
|
2133
2283
|
*/
|
|
2134
|
-
|
|
2284
|
+
updateTask(teamId: string, taskId: string, updates: Partial<TaskUpdatable>): Promise<TeamTask | null>;
|
|
2135
2285
|
/**
|
|
2136
|
-
*
|
|
2137
|
-
* @
|
|
2138
|
-
* @param callback Callback function
|
|
2286
|
+
* Remove a task from the list.
|
|
2287
|
+
* @returns true if removed, false if not found.
|
|
2139
2288
|
*/
|
|
2140
|
-
|
|
2289
|
+
removeTask(teamId: string, taskId: string): Promise<boolean>;
|
|
2141
2290
|
/**
|
|
2142
|
-
*
|
|
2143
|
-
*
|
|
2144
|
-
* @
|
|
2291
|
+
* Claim a specific task by ID: set assignee to agentId and status to CLAIMED.
|
|
2292
|
+
* Only succeeds if the task is PENDING and all its dependencies are COMPLETED.
|
|
2293
|
+
* @returns The claimed task, or null if not found / not claimable.
|
|
2145
2294
|
*/
|
|
2146
|
-
|
|
2295
|
+
claimTaskById(teamId: string, taskId: string, agentId: string): Promise<TeamTask | null>;
|
|
2296
|
+
/**
|
|
2297
|
+
* Mark a task as completed with a result summary.
|
|
2298
|
+
* @returns The updated task, or null if not found.
|
|
2299
|
+
*/
|
|
2300
|
+
completeTask(teamId: string, taskId: string, result: string): Promise<TeamTask | null>;
|
|
2301
|
+
/**
|
|
2302
|
+
* Mark a task as failed with an error message.
|
|
2303
|
+
* @returns The updated task, or null if not found.
|
|
2304
|
+
*/
|
|
2305
|
+
failTask(teamId: string, taskId: string, error: string): Promise<TeamTask | null>;
|
|
2306
|
+
/**
|
|
2307
|
+
* Get a single task by ID.
|
|
2308
|
+
*/
|
|
2309
|
+
getTask(teamId: string, taskId: string): Promise<TeamTask | null>;
|
|
2310
|
+
/**
|
|
2311
|
+
* Get all tasks with a given status.
|
|
2312
|
+
*/
|
|
2313
|
+
getTasksByStatus(teamId: string, status: TaskStatus): Promise<TeamTask[]>;
|
|
2314
|
+
/**
|
|
2315
|
+
* Get all tasks for the team.
|
|
2316
|
+
*/
|
|
2317
|
+
getAllTasks(teamId: string): Promise<TeamTask[]>;
|
|
2318
|
+
/**
|
|
2319
|
+
* Check whether all tasks are in a terminal state (COMPLETED or FAILED)
|
|
2320
|
+
* and no tasks are PENDING, CLAIMED, or IN_PROGRESS.
|
|
2321
|
+
*/
|
|
2322
|
+
isAllDone(teamId: string): Promise<boolean>;
|
|
2323
|
+
/**
|
|
2324
|
+
* Check whether there is at least one PENDING task whose dependencies
|
|
2325
|
+
* are all COMPLETED (i.e. a task that can be claimed right now).
|
|
2326
|
+
*/
|
|
2327
|
+
hasClaimable(teamId: string): Promise<boolean>;
|
|
2328
|
+
/**
|
|
2329
|
+
* Subscribe to task events. Used by persistent teammates to sleep
|
|
2330
|
+
* until new claimable tasks appear (via "task:added" / "task:completed").
|
|
2331
|
+
*/
|
|
2332
|
+
onTaskEvent(teamId: string, event: TaskEvent, callback: (task: TeamTask) => void): void;
|
|
2333
|
+
/**
|
|
2334
|
+
* Remove all tasks for a team (used when disbanding a team).
|
|
2335
|
+
*/
|
|
2336
|
+
clearTeam(teamId: string): void;
|
|
2337
|
+
}
|
|
2338
|
+
/**
|
|
2339
|
+
* External shared storage for inter-agent messages.
|
|
2340
|
+
*
|
|
2341
|
+
* Leader and teammates use the same store instance to send and receive
|
|
2342
|
+
* messages. Implementations can be in-memory, database, etc.
|
|
2343
|
+
*/
|
|
2344
|
+
interface MailboxStore {
|
|
2345
|
+
/**
|
|
2346
|
+
* Send a direct message from one agent to another.
|
|
2347
|
+
* @returns The created message.
|
|
2348
|
+
*/
|
|
2349
|
+
sendMessage(teamId: string, from: string, to: string, content: string, type?: MessageType): Promise<MailboxMessage>;
|
|
2350
|
+
/**
|
|
2351
|
+
* Send a message to all registered agents in the team.
|
|
2352
|
+
* @returns Array of created messages (one per recipient).
|
|
2353
|
+
*/
|
|
2354
|
+
broadcastMessage(teamId: string, from: string, content: string, type?: MessageType): Promise<MailboxMessage[]>;
|
|
2355
|
+
/**
|
|
2356
|
+
* Get all messages addressed to a specific agent (including broadcasts).
|
|
2357
|
+
*/
|
|
2358
|
+
getMessages(teamId: string, agentId: string): Promise<MailboxMessage[]>;
|
|
2359
|
+
/**
|
|
2360
|
+
* Get only unread messages for an agent.
|
|
2361
|
+
*/
|
|
2362
|
+
getUnreadMessages(teamId: string, agentId: string): Promise<MailboxMessage[]>;
|
|
2363
|
+
/**
|
|
2364
|
+
* Mark a specific message as read.
|
|
2365
|
+
*/
|
|
2366
|
+
markAsRead(teamId: string, agentId: string, messageId: string): Promise<void>;
|
|
2367
|
+
/**
|
|
2368
|
+
* Register an agent so it can receive broadcast messages.
|
|
2369
|
+
*/
|
|
2370
|
+
registerAgent(teamId: string, agentId: string): Promise<void>;
|
|
2371
|
+
/**
|
|
2372
|
+
* Unregister an agent.
|
|
2373
|
+
*/
|
|
2374
|
+
unregisterAgent(teamId: string, agentId: string): Promise<void>;
|
|
2375
|
+
/**
|
|
2376
|
+
* Get all registered agent IDs for a team.
|
|
2377
|
+
*/
|
|
2378
|
+
getRegisteredAgents(teamId: string): Promise<string[]>;
|
|
2379
|
+
/**
|
|
2380
|
+
* Subscribe to new messages for a specific agent.
|
|
2381
|
+
* Used for real-time notification so teammates can react promptly.
|
|
2382
|
+
*/
|
|
2383
|
+
onMessage(teamId: string, agentId: string, callback: (msg: MailboxMessage) => void): void;
|
|
2384
|
+
/**
|
|
2385
|
+
* Unsubscribe from message events.
|
|
2386
|
+
*/
|
|
2387
|
+
offMessage(teamId: string, agentId: string, callback: (msg: MailboxMessage) => void): void;
|
|
2388
|
+
/**
|
|
2389
|
+
* Subscribe to all new messages in a team.
|
|
2390
|
+
* Used for real-time notification of any message in the team.
|
|
2391
|
+
*/
|
|
2392
|
+
onTeamMessage(teamId: string, callback: (msg: MailboxMessage) => void): void;
|
|
2393
|
+
/**
|
|
2394
|
+
* Unsubscribe from team message events.
|
|
2395
|
+
*/
|
|
2396
|
+
offTeamMessage(teamId: string, callback: (msg: MailboxMessage) => void): void;
|
|
2397
|
+
/**
|
|
2398
|
+
* Get all messages for all agents in a team.
|
|
2399
|
+
*/
|
|
2400
|
+
getAllTeamMessages(teamId: string): Promise<MailboxMessage[]>;
|
|
2401
|
+
/**
|
|
2402
|
+
* Remove all messages for a team (used when disbanding a team).
|
|
2403
|
+
*/
|
|
2404
|
+
clearTeam(teamId: string): void;
|
|
2147
2405
|
}
|
|
2148
|
-
declare const eventBus: EventBus;
|
|
2149
2406
|
|
|
2150
|
-
|
|
2151
|
-
|
|
2152
|
-
|
|
2407
|
+
/**
|
|
2408
|
+
* Agent Team - Core Type Definitions
|
|
2409
|
+
*
|
|
2410
|
+
* Shared types used by TaskListStore, MailboxStore, middleware, and the AgentTeam facade.
|
|
2411
|
+
*/
|
|
2412
|
+
|
|
2413
|
+
/**
|
|
2414
|
+
* Status of a task in the shared task list.
|
|
2415
|
+
*/
|
|
2416
|
+
declare enum TaskStatus {
|
|
2417
|
+
PENDING = "pending",
|
|
2418
|
+
CLAIMED = "claimed",
|
|
2419
|
+
IN_PROGRESS = "in_progress",
|
|
2420
|
+
COMPLETED = "completed",
|
|
2421
|
+
FAILED = "failed"
|
|
2422
|
+
}
|
|
2423
|
+
/**
|
|
2424
|
+
* Events emitted by a TaskListStore when task state changes.
|
|
2425
|
+
*/
|
|
2426
|
+
type TaskEvent = "task:added" | "task:claimed" | "task:completed" | "task:failed" | "task:removed";
|
|
2427
|
+
/**
|
|
2428
|
+
* A task stored in the shared task list.
|
|
2429
|
+
*/
|
|
2430
|
+
interface TeamTask {
|
|
2431
|
+
/** Unique task identifier */
|
|
2432
|
+
id: string;
|
|
2433
|
+
/** Short title for the task */
|
|
2434
|
+
title: string;
|
|
2435
|
+
/** Detailed description of what needs to be done */
|
|
2436
|
+
description: string;
|
|
2437
|
+
/** Current status */
|
|
2438
|
+
status: TaskStatus;
|
|
2439
|
+
/** Name of the teammate that claimed this task */
|
|
2440
|
+
assignee?: string;
|
|
2441
|
+
/** Result summary when completed */
|
|
2442
|
+
result?: string;
|
|
2443
|
+
/** Error message when failed */
|
|
2444
|
+
error?: string;
|
|
2445
|
+
/** IDs of tasks that must be completed before this one can be claimed */
|
|
2446
|
+
dependencies: string[];
|
|
2447
|
+
/** When the task was created */
|
|
2448
|
+
createdAt: Date;
|
|
2449
|
+
/** When the task was last updated */
|
|
2450
|
+
updatedAt: Date;
|
|
2451
|
+
}
|
|
2452
|
+
/**
|
|
2453
|
+
* Input for creating a new task.
|
|
2454
|
+
*/
|
|
2455
|
+
interface TaskSpec {
|
|
2456
|
+
id: string;
|
|
2457
|
+
title: string;
|
|
2458
|
+
description: string;
|
|
2459
|
+
assignee?: string;
|
|
2460
|
+
dependencies?: string[];
|
|
2461
|
+
}
|
|
2462
|
+
/**
|
|
2463
|
+
* Fields that can be updated on an existing task.
|
|
2464
|
+
*/
|
|
2465
|
+
interface TaskUpdatable {
|
|
2466
|
+
title?: string;
|
|
2467
|
+
description?: string;
|
|
2468
|
+
assignee?: string;
|
|
2469
|
+
status?: TaskStatus;
|
|
2470
|
+
dependencies?: string[];
|
|
2471
|
+
}
|
|
2472
|
+
/**
|
|
2473
|
+
* Type of an inter-agent message in the mailbox.
|
|
2474
|
+
* Different tools and flows use different types when storing messages.
|
|
2475
|
+
*/
|
|
2476
|
+
declare enum MessageType {
|
|
2477
|
+
/** One-to-one message (send_message tool) */
|
|
2478
|
+
DIRECT_MESSAGE = "direct_message",
|
|
2479
|
+
/** Message to all teammates (broadcast_message tool) */
|
|
2480
|
+
BROADCAST = "broadcast",
|
|
2481
|
+
/** Teammate submits execution plan to team_lead for approval */
|
|
2482
|
+
PLAN_REQUEST = "plan_request",
|
|
2483
|
+
/** Team_lead approves or rejects plan (feedback to teammate) */
|
|
2484
|
+
PLAN_FEEDBACK = "plan_feedback",
|
|
2485
|
+
/** Team_lead instructs team to shut down (e.g. disband_team) */
|
|
2486
|
+
SHUTDOWN_REQUEST = "shutdown_request",
|
|
2487
|
+
/** Teammate acknowledges shutdown */
|
|
2488
|
+
SHUTDOWN_RESPONSE = "shutdown_response",
|
|
2489
|
+
/** From TaskCompleted/TeammateIdle hook or system: quality issue or continue-work reminder */
|
|
2490
|
+
TASK_FEEDBACK = "task_feedback",
|
|
2491
|
+
/** Idle notification, task status change, or other status update */
|
|
2492
|
+
STATUS_UPDATE = "status_update"
|
|
2493
|
+
}
|
|
2494
|
+
/**
|
|
2495
|
+
* A message stored in the mailbox.
|
|
2496
|
+
*/
|
|
2497
|
+
interface MailboxMessage {
|
|
2498
|
+
/** Unique message identifier */
|
|
2499
|
+
id: string;
|
|
2500
|
+
/** Sender agent name */
|
|
2501
|
+
from: string;
|
|
2502
|
+
/** Recipient agent name (or "__broadcast__" for broadcasts) */
|
|
2503
|
+
to: string;
|
|
2504
|
+
/** Message content */
|
|
2505
|
+
content: string;
|
|
2506
|
+
/** When the message was sent */
|
|
2507
|
+
timestamp: Date;
|
|
2508
|
+
/** Message type */
|
|
2509
|
+
type: MessageType;
|
|
2510
|
+
/** Whether the recipient has read this message */
|
|
2511
|
+
read: boolean;
|
|
2512
|
+
}
|
|
2513
|
+
/**
|
|
2514
|
+
* Specification for a teammate agent.
|
|
2515
|
+
* Configured at team creation time; the `create_team` tool matches teammate
|
|
2516
|
+
* names from the LLM's plan against these specs to get tools/model/prompt.
|
|
2517
|
+
*/
|
|
2518
|
+
interface TeammateSpec {
|
|
2519
|
+
/** Unique name for this teammate (used as agent ID) */
|
|
2520
|
+
name: string;
|
|
2521
|
+
/** Role category (e.g. "research", "writing", "review") */
|
|
2522
|
+
role: string;
|
|
2523
|
+
/** Human-readable description of what this teammate does */
|
|
2524
|
+
description: string;
|
|
2525
|
+
/** Model override (defaults to team-level model) */
|
|
2526
|
+
model?: LanguageModelLike | string;
|
|
2527
|
+
/** Tools this teammate has access to (in addition to team tools) */
|
|
2528
|
+
tools?: StructuredTool[];
|
|
2529
|
+
/** Custom system prompt for this teammate */
|
|
2530
|
+
systemPrompt?: string;
|
|
2531
|
+
/** Additional middleware for this teammate */
|
|
2532
|
+
middleware?: AgentMiddleware[];
|
|
2533
|
+
}
|
|
2534
|
+
/**
|
|
2535
|
+
* Configuration for creating an agent team.
|
|
2536
|
+
*/
|
|
2537
|
+
interface TeamConfig {
|
|
2538
|
+
/** Available teammate specifications (the LLM picks from these by name) */
|
|
2539
|
+
teammates: TeammateSpec[];
|
|
2540
|
+
/** Maximum number of teammates running concurrently (default: teammates.length) */
|
|
2541
|
+
maxConcurrency?: number;
|
|
2542
|
+
/** Model for the team lead agent */
|
|
2543
|
+
model?: LanguageModelLike | string;
|
|
2544
|
+
/** Custom system prompt for the team lead */
|
|
2545
|
+
systemPrompt?: string;
|
|
2546
|
+
/** Tools available to the team lead */
|
|
2547
|
+
tools?: StructuredTool[];
|
|
2548
|
+
/** Checkpointer for persisting agent state between runs */
|
|
2549
|
+
checkpointer?: BaseCheckpointSaver | boolean;
|
|
2550
|
+
/** Pluggable task list store (default: InMemoryTaskListStore) */
|
|
2551
|
+
taskListStore?: TaskListStore;
|
|
2552
|
+
/** Pluggable mailbox store (default: InMemoryMailboxStore) */
|
|
2553
|
+
mailboxStore?: MailboxStore;
|
|
2554
|
+
/** Additional middleware for the team lead agent */
|
|
2555
|
+
middleware?: AgentMiddleware[];
|
|
2556
|
+
/**
|
|
2557
|
+
* Schedule lattice key for polling task list / mailbox.
|
|
2558
|
+
* When set, teammates use scheduled polling instead of event-driven wait.
|
|
2559
|
+
* Requires the app to register the schedule lattice first.
|
|
2560
|
+
*/
|
|
2561
|
+
scheduleLatticeKey?: string;
|
|
2562
|
+
/** Poll interval in ms when using schedule lattice (default: 5000) */
|
|
2563
|
+
pollIntervalMs?: number;
|
|
2564
|
+
/** Filesystem backend for sandboxed file operations */
|
|
2565
|
+
backend?: (config: {
|
|
2566
|
+
state: unknown;
|
|
2567
|
+
store?: any;
|
|
2568
|
+
}) => Promise<any>;
|
|
2569
|
+
}
|
|
2570
|
+
|
|
2571
|
+
/**
|
|
2572
|
+
* InMemoryTaskListStore
|
|
2573
|
+
*
|
|
2574
|
+
* In-memory implementation of TaskListStore.
|
|
2575
|
+
* Tasks are organised by teamId, following the same pattern as
|
|
2576
|
+
* InMemoryThreadStore (Map<teamId, Map<taskId, TeamTask>>).
|
|
2577
|
+
*
|
|
2578
|
+
* Uses an internal EventEmitter so persistent teammates can sleep
|
|
2579
|
+
* until claimable tasks appear instead of busy-polling.
|
|
2580
|
+
*/
|
|
2581
|
+
|
|
2582
|
+
declare class InMemoryTaskListStore implements TaskListStore {
|
|
2583
|
+
/** Map<teamId, Map<taskId, TeamTask>> */
|
|
2584
|
+
private tasks;
|
|
2585
|
+
/** EventEmitter for task lifecycle events */
|
|
2586
|
+
private emitter;
|
|
2587
|
+
/** Auto-incrementing ID counter */
|
|
2588
|
+
private idCounter;
|
|
2589
|
+
constructor();
|
|
2590
|
+
/** Get or create the task map for a team. */
|
|
2591
|
+
private getTeamTasks;
|
|
2592
|
+
/** Generate a unique task ID. */
|
|
2593
|
+
private nextId;
|
|
2594
|
+
/** Emit a scoped event: `${teamId}:${event}`. */
|
|
2595
|
+
private emit;
|
|
2596
|
+
/**
|
|
2597
|
+
* Resolve dependency references by task IDs.
|
|
2598
|
+
*/
|
|
2599
|
+
private resolveDependencies;
|
|
2600
|
+
/**
|
|
2601
|
+
* Check whether all dependencies of a task are in COMPLETED status.
|
|
2602
|
+
*/
|
|
2603
|
+
private areDependenciesSatisfied;
|
|
2604
|
+
addTask(teamId: string, spec: TaskSpec): Promise<TeamTask>;
|
|
2605
|
+
addTasks(teamId: string, specs: TaskSpec[]): Promise<TeamTask[]>;
|
|
2606
|
+
updateTask(teamId: string, taskId: string, updates: Partial<TaskUpdatable>): Promise<TeamTask | null>;
|
|
2607
|
+
removeTask(teamId: string, taskId: string): Promise<boolean>;
|
|
2608
|
+
/**
|
|
2609
|
+
* Claim a specific task by ID: set assignee to agentId and status to CLAIMED.
|
|
2610
|
+
* Only succeeds if the task is PENDING and all dependencies are COMPLETED.
|
|
2611
|
+
*/
|
|
2612
|
+
claimTaskById(teamId: string, taskId: string, agentId: string): Promise<TeamTask | null>;
|
|
2613
|
+
completeTask(teamId: string, taskId: string, result: string): Promise<TeamTask | null>;
|
|
2614
|
+
failTask(teamId: string, taskId: string, error: string): Promise<TeamTask | null>;
|
|
2615
|
+
getTask(teamId: string, taskId: string): Promise<TeamTask | null>;
|
|
2616
|
+
getTasksByStatus(teamId: string, status: TaskStatus): Promise<TeamTask[]>;
|
|
2617
|
+
getAllTasks(teamId: string): Promise<TeamTask[]>;
|
|
2618
|
+
isAllDone(teamId: string): Promise<boolean>;
|
|
2619
|
+
hasClaimable(teamId: string): Promise<boolean>;
|
|
2620
|
+
onTaskEvent(teamId: string, event: TaskEvent, callback: (task: TeamTask) => void): void;
|
|
2621
|
+
offTaskEvent(teamId: string, event: TaskEvent, callback: (task: TeamTask) => void): void;
|
|
2622
|
+
/** Remove all tasks for a team (useful for cleanup / testing). */
|
|
2623
|
+
clearTeam(teamId: string): void;
|
|
2624
|
+
/** Remove all tasks across all teams (useful for testing). */
|
|
2625
|
+
clear(): void;
|
|
2626
|
+
}
|
|
2627
|
+
|
|
2628
|
+
/**
|
|
2629
|
+
* InMemoryMailboxStore
|
|
2630
|
+
*
|
|
2631
|
+
* In-memory implementation of MailboxStore.
|
|
2632
|
+
* Messages are organised by teamId -> agentId, following the same
|
|
2633
|
+
* Map nesting pattern as InMemoryThreadStore.
|
|
2634
|
+
*
|
|
2635
|
+
* Uses an internal EventEmitter so agents can be notified of new
|
|
2636
|
+
* messages in real time without polling.
|
|
2637
|
+
*/
|
|
2638
|
+
|
|
2639
|
+
declare class InMemoryMailboxStore implements MailboxStore {
|
|
2640
|
+
/** Map<teamId, Map<agentId, MailboxMessage[]>> */
|
|
2641
|
+
private messages;
|
|
2642
|
+
/** Map<teamId, Set<agentId>> -- registered agents for broadcast */
|
|
2153
2643
|
private agents;
|
|
2154
|
-
|
|
2155
|
-
|
|
2156
|
-
|
|
2157
|
-
|
|
2158
|
-
|
|
2159
|
-
|
|
2160
|
-
|
|
2161
|
-
|
|
2644
|
+
/** EventEmitter for real-time message notifications */
|
|
2645
|
+
private emitter;
|
|
2646
|
+
/** Auto-incrementing message ID counter */
|
|
2647
|
+
private idCounter;
|
|
2648
|
+
constructor();
|
|
2649
|
+
/** Get or create the agent message list for a team. */
|
|
2650
|
+
private getAgentMessages;
|
|
2651
|
+
/** Generate a unique message ID. */
|
|
2652
|
+
private nextId;
|
|
2653
|
+
/** Store a message and emit a real-time event for the recipient. */
|
|
2654
|
+
private storeAndNotify;
|
|
2655
|
+
sendMessage(teamId: string, from: string, to: string, content: string, type?: MessageType): Promise<MailboxMessage>;
|
|
2656
|
+
broadcastMessage(teamId: string, from: string, content: string, type?: MessageType): Promise<MailboxMessage[]>;
|
|
2657
|
+
getMessages(teamId: string, agentId: string): Promise<MailboxMessage[]>;
|
|
2658
|
+
getUnreadMessages(teamId: string, agentId: string): Promise<MailboxMessage[]>;
|
|
2659
|
+
markAsRead(teamId: string, agentId: string, messageId: string): Promise<void>;
|
|
2660
|
+
registerAgent(teamId: string, agentId: string): Promise<void>;
|
|
2661
|
+
unregisterAgent(teamId: string, agentId: string): Promise<void>;
|
|
2662
|
+
getRegisteredAgents(teamId: string): Promise<string[]>;
|
|
2663
|
+
onMessage(teamId: string, agentId: string, callback: (msg: MailboxMessage) => void): void;
|
|
2664
|
+
offMessage(teamId: string, agentId: string, callback: (msg: MailboxMessage) => void): void;
|
|
2665
|
+
onTeamMessage(teamId: string, callback: (msg: MailboxMessage) => void): void;
|
|
2666
|
+
offTeamMessage(teamId: string, callback: (msg: MailboxMessage) => void): void;
|
|
2667
|
+
getAllTeamMessages(teamId: string): Promise<MailboxMessage[]>;
|
|
2668
|
+
/** Remove all data for a team (messages + registrations). */
|
|
2669
|
+
clearTeam(teamId: string): void;
|
|
2670
|
+
/** Remove all data across all teams. */
|
|
2671
|
+
clear(): void;
|
|
2162
2672
|
}
|
|
2163
2673
|
|
|
2164
|
-
|
|
2674
|
+
/**
|
|
2675
|
+
* Agent Team - Team Middleware
|
|
2676
|
+
*
|
|
2677
|
+
* createTeamMiddleware() provides the TeamLead agent with tools to
|
|
2678
|
+
* manage a dynamic team:
|
|
2679
|
+
*
|
|
2680
|
+
* create_team -- non-blocking: spawn teammates + populate task list
|
|
2681
|
+
* add_tasks -- add new tasks at any time (evolutionary)
|
|
2682
|
+
* assign_task -- set a task's assignee (reassign to a teammate)
|
|
2683
|
+
* set_task_status -- set a task's status (pending, claimed, in_progress, completed, failed)
|
|
2684
|
+
* set_task_dependencies -- set a task's dependency list
|
|
2685
|
+
* check_tasks -- get current task list status
|
|
2686
|
+
* send_message -- send message to a teammate
|
|
2687
|
+
* read_messages -- read unread messages from teammates
|
|
2688
|
+
*
|
|
2689
|
+
* Patterns referenced from deep_agent_new/middleware/subagents.ts:
|
|
2690
|
+
* - createMiddleware() + wrapModelCall for system prompt injection
|
|
2691
|
+
* - Agent creation via createAgent() from langchain
|
|
2692
|
+
* - State filtering (filterStateForSubagent logic)
|
|
2693
|
+
* - ToolMessage returns
|
|
2694
|
+
*/
|
|
2695
|
+
|
|
2696
|
+
/**
|
|
2697
|
+
* Options for creating the team middleware.
|
|
2698
|
+
*/
|
|
2699
|
+
interface TeamMiddlewareOptions {
|
|
2700
|
+
/** Team configuration with teammate specs */
|
|
2701
|
+
teamConfig: TeamConfig;
|
|
2702
|
+
/** Task list store instance (shared across all agents) */
|
|
2703
|
+
taskListStore: TaskListStore;
|
|
2704
|
+
/** Mailbox store instance (shared across all agents) */
|
|
2705
|
+
mailboxStore: MailboxStore;
|
|
2706
|
+
}
|
|
2707
|
+
/**
|
|
2708
|
+
* Create the team middleware that gives the TeamLead agent tools to
|
|
2709
|
+
* manage a dynamic team with shared task list and mailbox.
|
|
2710
|
+
*/
|
|
2711
|
+
declare function createTeamMiddleware(options: TeamMiddlewareOptions): AgentMiddleware;
|
|
2712
|
+
|
|
2713
|
+
/**
|
|
2714
|
+
* Agent Team - Teammate Tools
|
|
2715
|
+
*
|
|
2716
|
+
* Factory that creates LangChain StructuredTools injected into each
|
|
2717
|
+
* teammate agent. These tools let teammates interact with the shared
|
|
2718
|
+
* TaskListStore and MailboxStore.
|
|
2719
|
+
*
|
|
2720
|
+
* Tools: claim_task, complete_task, fail_task, send_message, read_messages
|
|
2721
|
+
*/
|
|
2722
|
+
|
|
2723
|
+
/**
|
|
2724
|
+
* Options for creating teammate tools.
|
|
2725
|
+
*/
|
|
2726
|
+
interface TeammateToolsOptions {
|
|
2727
|
+
/** Team identifier (scopes store operations) */
|
|
2728
|
+
teamId: string;
|
|
2729
|
+
/** This teammate's agent name / ID */
|
|
2730
|
+
agentId: string;
|
|
2731
|
+
/** Shared task list store */
|
|
2732
|
+
taskListStore: TaskListStore;
|
|
2733
|
+
/** Shared mailbox store */
|
|
2734
|
+
mailboxStore: MailboxStore;
|
|
2735
|
+
}
|
|
2736
|
+
/**
|
|
2737
|
+
* Create the set of tools injected into each teammate agent.
|
|
2738
|
+
*
|
|
2739
|
+
* These tools give the teammate access to:
|
|
2740
|
+
* - Task lifecycle: claim_task, complete_task, fail_task
|
|
2741
|
+
* - Communication: send_message, read_messages
|
|
2742
|
+
*/
|
|
2743
|
+
declare function createTeammateTools(options: TeammateToolsOptions): StructuredTool[];
|
|
2744
|
+
|
|
2745
|
+
/**
|
|
2746
|
+
* Agent Graph Builder 接口
|
|
2747
|
+
*
|
|
2748
|
+
* 策略模式的核心接口,定义了构建Agent Graph的方法
|
|
2749
|
+
*/
|
|
2750
|
+
|
|
2751
|
+
interface AgentGraphBuilder {
|
|
2752
|
+
/**
|
|
2753
|
+
* 构建Agent Graph
|
|
2754
|
+
*
|
|
2755
|
+
* @param agentLattice Agent Lattice对象
|
|
2756
|
+
* @param params Agent构建参数
|
|
2757
|
+
* @returns 返回CompiledGraph对象
|
|
2758
|
+
*/
|
|
2759
|
+
build(agentLattice: AgentLattice, params: AgentBuildParams): AgentClient;
|
|
2760
|
+
}
|
|
2761
|
+
|
|
2762
|
+
/**
|
|
2763
|
+
* Team Agent Graph Builder
|
|
2764
|
+
*
|
|
2765
|
+
* Implements AgentGraphBuilder for AgentType.TEAM.
|
|
2766
|
+
* Bridges the AgentConfig registration system with createAgentTeam(),
|
|
2767
|
+
* resolving tool keys and model keys into concrete instances.
|
|
2768
|
+
*/
|
|
2769
|
+
|
|
2770
|
+
declare class TeamAgentGraphBuilder implements AgentGraphBuilder {
|
|
2771
|
+
/**
|
|
2772
|
+
* Build a Team agent from the registered AgentLattice config.
|
|
2773
|
+
*
|
|
2774
|
+
* @param agentLattice - The AgentLattice containing the TeamAgentConfig
|
|
2775
|
+
* @param params - Build params with resolved tools and model
|
|
2776
|
+
* @returns AgentClient (the TeamLead ReactAgent)
|
|
2777
|
+
*/
|
|
2778
|
+
build(agentLattice: AgentLattice, params: AgentBuildParams): AgentClient;
|
|
2779
|
+
}
|
|
2780
|
+
|
|
2781
|
+
/**
|
|
2782
|
+
* Agent Team - High-level Facade
|
|
2783
|
+
*
|
|
2784
|
+
* createAgentTeam() wires together the TaskListStore, MailboxStore,
|
|
2785
|
+
* and team middleware to produce a ready-to-use TeamLead ReactAgent.
|
|
2786
|
+
*
|
|
2787
|
+
* Usage:
|
|
2788
|
+
*
|
|
2789
|
+
* ```typescript
|
|
2790
|
+
* import { createAgentTeam } from "@axiom-lattice/core";
|
|
2791
|
+
*
|
|
2792
|
+
* const team = createAgentTeam({
|
|
2793
|
+
* teammates: [
|
|
2794
|
+
* { name: "researcher", role: "research", description: "Web research", tools: [searchTool] },
|
|
2795
|
+
* { name: "writer", role: "writing", description: "Report writing", tools: [writeTool] },
|
|
2796
|
+
* ],
|
|
2797
|
+
* maxConcurrency: 3,
|
|
2798
|
+
* });
|
|
2799
|
+
*
|
|
2800
|
+
* await team.invoke({
|
|
2801
|
+
* messages: [{ role: "human", content: "Research and write a report on X" }],
|
|
2802
|
+
* });
|
|
2803
|
+
* ```
|
|
2804
|
+
*/
|
|
2805
|
+
|
|
2806
|
+
/**
|
|
2807
|
+
* Create an agent team: a TeamLead ReactAgent backed by shared
|
|
2808
|
+
* TaskListStore and MailboxStore with pre-configured teammates.
|
|
2809
|
+
*
|
|
2810
|
+
* @param config - Team configuration (teammates, model, stores, etc.)
|
|
2811
|
+
* @returns A ReactAgent that acts as the TeamLead
|
|
2812
|
+
*/
|
|
2813
|
+
declare function createAgentTeam(config: TeamConfig): ReactAgent<any, any, any, any>;
|
|
2814
|
+
|
|
2815
|
+
/**
|
|
2816
|
+
* Protocol definition for pluggable memory backends.
|
|
2817
|
+
*
|
|
2818
|
+
* This module defines the BackendProtocol that all backend implementations
|
|
2819
|
+
* must follow. Backends can store files in different locations (state, filesystem,
|
|
2820
|
+
* database, etc.) and provide a uniform interface for file operations.
|
|
2821
|
+
*/
|
|
2822
|
+
|
|
2823
|
+
type MaybePromise<T> = T | Promise<T>;
|
|
2824
|
+
/**
|
|
2825
|
+
* Structured file listing info.
|
|
2826
|
+
*
|
|
2827
|
+
* Minimal contract used across backends. Only "path" is required.
|
|
2828
|
+
* Other fields are best-effort and may be absent depending on backend.
|
|
2829
|
+
*/
|
|
2830
|
+
interface FileInfo {
|
|
2831
|
+
/** File path */
|
|
2832
|
+
path: string;
|
|
2833
|
+
/** Whether this is a directory */
|
|
2834
|
+
is_dir?: boolean;
|
|
2835
|
+
/** File size in bytes (approximate) */
|
|
2836
|
+
size?: number;
|
|
2837
|
+
/** ISO 8601 timestamp of last modification */
|
|
2838
|
+
modified_at?: string;
|
|
2839
|
+
}
|
|
2840
|
+
/**
|
|
2841
|
+
* Structured grep match entry.
|
|
2842
|
+
*/
|
|
2843
|
+
interface GrepMatch {
|
|
2844
|
+
/** File path where match was found */
|
|
2845
|
+
path: string;
|
|
2846
|
+
/** Line number (1-indexed) */
|
|
2847
|
+
line: number;
|
|
2848
|
+
/** The matching line text */
|
|
2849
|
+
text: string;
|
|
2850
|
+
}
|
|
2851
|
+
/**
|
|
2852
|
+
* File data structure used by backends.
|
|
2853
|
+
*
|
|
2854
|
+
* All file data is represented as objects with this structure:
|
|
2855
|
+
*/
|
|
2856
|
+
interface FileData {
|
|
2857
|
+
/** Lines of text content */
|
|
2858
|
+
content: string[];
|
|
2859
|
+
/** ISO format timestamp of creation */
|
|
2860
|
+
created_at: string;
|
|
2861
|
+
/** ISO format timestamp of last modification */
|
|
2862
|
+
modified_at: string;
|
|
2863
|
+
}
|
|
2864
|
+
/**
|
|
2865
|
+
* Result from backend write operations.
|
|
2866
|
+
*
|
|
2867
|
+
* Checkpoint backends populate filesUpdate with {file_path: file_data} for LangGraph state.
|
|
2868
|
+
* External backends set filesUpdate to null (already persisted to disk/S3/database/etc).
|
|
2869
|
+
*/
|
|
2870
|
+
interface WriteResult {
|
|
2871
|
+
/** Error message on failure, undefined on success */
|
|
2872
|
+
error?: string;
|
|
2873
|
+
/** File path of written file, undefined on failure */
|
|
2874
|
+
path?: string;
|
|
2875
|
+
/**
|
|
2876
|
+
* State update dict for checkpoint backends, null for external storage.
|
|
2877
|
+
* Checkpoint backends populate this with {file_path: file_data} for LangGraph state.
|
|
2878
|
+
* External backends set null (already persisted to disk/S3/database/etc).
|
|
2879
|
+
*/
|
|
2880
|
+
filesUpdate?: Record<string, FileData> | null;
|
|
2881
|
+
/** Metadata for the write operation, attached to the ToolMessage */
|
|
2882
|
+
metadata?: Record<string, unknown>;
|
|
2883
|
+
}
|
|
2884
|
+
/**
|
|
2885
|
+
* Result from backend edit operations.
|
|
2886
|
+
*
|
|
2887
|
+
* Checkpoint backends populate filesUpdate with {file_path: file_data} for LangGraph state.
|
|
2888
|
+
* External backends set filesUpdate to null (already persisted to disk/S3/database/etc).
|
|
2889
|
+
*/
|
|
2890
|
+
interface EditResult {
|
|
2891
|
+
/** Error message on failure, undefined on success */
|
|
2892
|
+
error?: string;
|
|
2893
|
+
/** File path of edited file, undefined on failure */
|
|
2894
|
+
path?: string;
|
|
2895
|
+
/**
|
|
2896
|
+
* State update dict for checkpoint backends, null for external storage.
|
|
2897
|
+
* Checkpoint backends populate this with {file_path: file_data} for LangGraph state.
|
|
2898
|
+
* External backends set null (already persisted to disk/S3/database/etc).
|
|
2899
|
+
*/
|
|
2900
|
+
filesUpdate?: Record<string, FileData> | null;
|
|
2901
|
+
/** Number of replacements made, undefined on failure */
|
|
2902
|
+
occurrences?: number;
|
|
2903
|
+
/** Metadata for the edit operation, attached to the ToolMessage */
|
|
2904
|
+
metadata?: Record<string, unknown>;
|
|
2905
|
+
}
|
|
2906
|
+
/**
|
|
2907
|
+
* Protocol for pluggable memory backends (single, unified).
|
|
2908
|
+
*
|
|
2909
|
+
* Backends can store files in different locations (state, filesystem, database, etc.)
|
|
2910
|
+
* and provide a uniform interface for file operations.
|
|
2911
|
+
*
|
|
2912
|
+
* All file data is represented as objects with the FileData structure.
|
|
2913
|
+
*
|
|
2914
|
+
* Methods can return either direct values or Promises, allowing both
|
|
2915
|
+
* synchronous and asynchronous implementations.
|
|
2916
|
+
*/
|
|
2917
|
+
interface BackendProtocol {
|
|
2918
|
+
/**
|
|
2919
|
+
* Structured listing with file metadata.
|
|
2920
|
+
*
|
|
2921
|
+
* Lists files and directories in the specified directory (non-recursive).
|
|
2922
|
+
* Directories have a trailing / in their path and is_dir=true.
|
|
2923
|
+
*
|
|
2924
|
+
* @param path - Absolute path to directory
|
|
2925
|
+
* @returns List of FileInfo objects for files and directories directly in the directory
|
|
2926
|
+
*/
|
|
2927
|
+
lsInfo(path: string): MaybePromise<FileInfo[]>;
|
|
2928
|
+
/**
|
|
2929
|
+
* Read file content with line numbers or an error string.
|
|
2930
|
+
*
|
|
2931
|
+
* @param filePath - Absolute file path
|
|
2932
|
+
* @param offset - Line offset to start reading from (0-indexed), default 0
|
|
2933
|
+
* @param limit - Maximum number of lines to read, default 2000
|
|
2934
|
+
* @returns Formatted file content with line numbers, or error message
|
|
2935
|
+
*/
|
|
2936
|
+
read(filePath: string, offset?: number, limit?: number): MaybePromise<string>;
|
|
2937
|
+
/**
|
|
2938
|
+
* Read file content as raw FileData.
|
|
2939
|
+
*
|
|
2940
|
+
* @param filePath - Absolute file path
|
|
2941
|
+
* @returns Raw file content as FileData
|
|
2942
|
+
*/
|
|
2943
|
+
readRaw(filePath: string): MaybePromise<FileData>;
|
|
2944
|
+
/**
|
|
2945
|
+
* Structured search results or error string for invalid input.
|
|
2946
|
+
*
|
|
2947
|
+
* Searches file contents for a regex pattern.
|
|
2948
|
+
*
|
|
2949
|
+
* @param pattern - Regex pattern to search for
|
|
2950
|
+
* @param path - Base path to search from (default: null)
|
|
2951
|
+
* @param glob - Optional glob pattern to filter files (e.g., "*.py")
|
|
2952
|
+
* @returns List of GrepMatch objects or error string for invalid regex
|
|
2953
|
+
*/
|
|
2954
|
+
grepRaw(pattern: string, path?: string | null, glob?: string | null): MaybePromise<GrepMatch[] | string>;
|
|
2955
|
+
/**
|
|
2956
|
+
* Structured glob matching returning FileInfo objects.
|
|
2957
|
+
*
|
|
2958
|
+
* @param pattern - Glob pattern (e.g., `*.py`, `**\/*.ts`)
|
|
2959
|
+
* @param path - Base path to search from (default: "/")
|
|
2960
|
+
* @returns List of FileInfo objects matching the pattern
|
|
2961
|
+
*/
|
|
2962
|
+
globInfo(pattern: string, path?: string): MaybePromise<FileInfo[]>;
|
|
2963
|
+
/**
|
|
2964
|
+
* Create a new file.
|
|
2965
|
+
*
|
|
2966
|
+
* @param filePath - Absolute file path
|
|
2967
|
+
* @param content - File content as string
|
|
2968
|
+
* @returns WriteResult with error populated on failure
|
|
2969
|
+
*/
|
|
2970
|
+
write(filePath: string, content: string): MaybePromise<WriteResult>;
|
|
2971
|
+
/**
|
|
2972
|
+
* Edit a file by replacing string occurrences.
|
|
2973
|
+
*
|
|
2974
|
+
* @param filePath - Absolute file path
|
|
2975
|
+
* @param oldString - String to find and replace
|
|
2976
|
+
* @param newString - Replacement string
|
|
2977
|
+
* @param replaceAll - If true, replace all occurrences (default: false)
|
|
2978
|
+
* @returns EditResult with error, path, filesUpdate, and occurrences
|
|
2979
|
+
*/
|
|
2980
|
+
edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): MaybePromise<EditResult>;
|
|
2981
|
+
}
|
|
2982
|
+
/**
|
|
2983
|
+
* State and store container for backend initialization.
|
|
2984
|
+
*
|
|
2985
|
+
* This provides a clean interface for what backends need to access:
|
|
2986
|
+
* - state: Current agent state (with files, messages, etc.)
|
|
2987
|
+
* - store: Optional persistent store for cross-conversation data
|
|
2988
|
+
*
|
|
2989
|
+
* Different contexts build this differently:
|
|
2990
|
+
* - Tools: Extract state via getCurrentTaskInput(config)
|
|
2991
|
+
* - Middleware: Use request.state directly
|
|
2992
|
+
*/
|
|
2993
|
+
interface StateAndStore {
|
|
2994
|
+
/** Current agent state with files, messages, etc. */
|
|
2995
|
+
state: unknown;
|
|
2996
|
+
/** Optional BaseStore for persistent cross-conversation storage */
|
|
2997
|
+
store?: BaseStore;
|
|
2998
|
+
/** Optional assistant ID for per-assistant isolation in store */
|
|
2999
|
+
assistantId?: string;
|
|
3000
|
+
threadId?: string;
|
|
3001
|
+
workspaceId?: string;
|
|
3002
|
+
projectId?: string;
|
|
3003
|
+
}
|
|
3004
|
+
/**
|
|
3005
|
+
* Factory function type for creating backend instances.
|
|
3006
|
+
*
|
|
3007
|
+
* Backends receive StateAndStore which contains the current state
|
|
3008
|
+
* and optional store, extracted from the execution context.
|
|
3009
|
+
*
|
|
3010
|
+
* @example
|
|
3011
|
+
* ```typescript
|
|
3012
|
+
* // Using in middleware
|
|
3013
|
+
* const middleware = createFilesystemMiddleware({
|
|
3014
|
+
* backend: (stateAndStore) => new StateBackend(stateAndStore)
|
|
3015
|
+
* });
|
|
3016
|
+
* ```
|
|
3017
|
+
*/
|
|
3018
|
+
type BackendFactory = (stateAndStore: StateAndStore) => Promise<BackendProtocol>;
|
|
3019
|
+
|
|
3020
|
+
/**
|
|
3021
|
+
* StateBackend: Store files in LangGraph agent state (ephemeral).
|
|
3022
|
+
*/
|
|
3023
|
+
|
|
3024
|
+
/**
|
|
3025
|
+
* Backend that stores files in agent state (ephemeral).
|
|
3026
|
+
*
|
|
3027
|
+
* Uses LangGraph's state management and checkpointing. Files persist within
|
|
3028
|
+
* a conversation thread but not across threads. State is automatically
|
|
3029
|
+
* checkpointed after each agent step.
|
|
3030
|
+
*
|
|
3031
|
+
* Special handling: Since LangGraph state must be updated via Command objects
|
|
3032
|
+
* (not direct mutation), operations return filesUpdate in WriteResult/EditResult
|
|
3033
|
+
* for the middleware to apply via Command.
|
|
3034
|
+
*/
|
|
3035
|
+
declare class StateBackend implements BackendProtocol {
|
|
3036
|
+
private stateAndStore;
|
|
3037
|
+
constructor(stateAndStore: StateAndStore);
|
|
3038
|
+
/**
|
|
3039
|
+
* Get files from current state.
|
|
3040
|
+
*/
|
|
3041
|
+
private getFiles;
|
|
3042
|
+
/**
|
|
3043
|
+
* List files and directories in the specified directory (non-recursive).
|
|
3044
|
+
*
|
|
3045
|
+
* @param path - Absolute path to directory
|
|
3046
|
+
* @returns List of FileInfo objects for files and directories directly in the directory.
|
|
3047
|
+
* Directories have a trailing / in their path and is_dir=true.
|
|
3048
|
+
*/
|
|
3049
|
+
lsInfo(path: string): FileInfo[];
|
|
3050
|
+
/**
|
|
3051
|
+
* Read file content with line numbers.
|
|
3052
|
+
*
|
|
3053
|
+
* @param filePath - Absolute file path
|
|
3054
|
+
* @param offset - Line offset to start reading from (0-indexed)
|
|
3055
|
+
* @param limit - Maximum number of lines to read
|
|
3056
|
+
* @returns Formatted file content with line numbers, or error message
|
|
3057
|
+
*/
|
|
3058
|
+
read(filePath: string, offset?: number, limit?: number): string;
|
|
3059
|
+
/**
|
|
3060
|
+
* Read file content as raw FileData.
|
|
3061
|
+
*
|
|
3062
|
+
* @param filePath - Absolute file path
|
|
3063
|
+
* @returns Raw file content as FileData
|
|
3064
|
+
*/
|
|
3065
|
+
readRaw(filePath: string): FileData;
|
|
3066
|
+
/**
|
|
3067
|
+
* Create a new file with content.
|
|
3068
|
+
* Returns WriteResult with filesUpdate to update LangGraph state.
|
|
3069
|
+
*/
|
|
3070
|
+
write(filePath: string, content: string): WriteResult;
|
|
3071
|
+
/**
|
|
3072
|
+
* Edit a file by replacing string occurrences.
|
|
3073
|
+
* Returns EditResult with filesUpdate and occurrences.
|
|
3074
|
+
*/
|
|
3075
|
+
edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): EditResult;
|
|
3076
|
+
/**
|
|
3077
|
+
* Structured search results or error string for invalid input.
|
|
3078
|
+
*/
|
|
3079
|
+
grepRaw(pattern: string, path?: string, glob?: string | null): GrepMatch[] | string;
|
|
3080
|
+
/**
|
|
3081
|
+
* Structured glob matching returning FileInfo objects.
|
|
3082
|
+
*/
|
|
3083
|
+
globInfo(pattern: string, path?: string): FileInfo[];
|
|
3084
|
+
}
|
|
3085
|
+
|
|
3086
|
+
/**
|
|
3087
|
+
* StoreBackend: Adapter for LangGraph's BaseStore (persistent, cross-thread).
|
|
3088
|
+
*/
|
|
3089
|
+
|
|
3090
|
+
/**
|
|
3091
|
+
* Backend that stores files in LangGraph's BaseStore (persistent).
|
|
3092
|
+
*
|
|
3093
|
+
* Uses LangGraph's Store for persistent, cross-conversation storage.
|
|
3094
|
+
* Files are organized via namespaces and persist across all threads.
|
|
3095
|
+
*
|
|
3096
|
+
* The namespace can include an optional assistant_id for multi-agent isolation.
|
|
3097
|
+
*/
|
|
3098
|
+
declare class StoreBackend implements BackendProtocol {
|
|
3099
|
+
private stateAndStore;
|
|
3100
|
+
constructor(stateAndStore: StateAndStore);
|
|
3101
|
+
/**
|
|
3102
|
+
* Get the store instance.
|
|
3103
|
+
*
|
|
3104
|
+
* @returns BaseStore instance
|
|
3105
|
+
* @throws Error if no store is available
|
|
3106
|
+
*/
|
|
3107
|
+
private getStore;
|
|
3108
|
+
/**
|
|
3109
|
+
* Get the namespace for store operations.
|
|
3110
|
+
*
|
|
3111
|
+
* If an assistant_id is available in stateAndStore, return
|
|
3112
|
+
* [assistant_id, "filesystem"] to provide per-assistant isolation.
|
|
3113
|
+
* Otherwise return ["filesystem"].
|
|
3114
|
+
*/
|
|
3115
|
+
protected getNamespace(): string[];
|
|
3116
|
+
/**
|
|
3117
|
+
* Convert a store Item to FileData format.
|
|
3118
|
+
*
|
|
3119
|
+
* @param storeItem - The store Item containing file data
|
|
3120
|
+
* @returns FileData object
|
|
3121
|
+
* @throws Error if required fields are missing or have incorrect types
|
|
3122
|
+
*/
|
|
3123
|
+
private convertStoreItemToFileData;
|
|
3124
|
+
/**
|
|
3125
|
+
* Convert FileData to a value suitable for store.put().
|
|
3126
|
+
*
|
|
3127
|
+
* @param fileData - The FileData to convert
|
|
3128
|
+
* @returns Object with content, created_at, and modified_at fields
|
|
3129
|
+
*/
|
|
3130
|
+
private convertFileDataToStoreValue;
|
|
3131
|
+
/**
|
|
3132
|
+
* Search store with automatic pagination to retrieve all results.
|
|
3133
|
+
*
|
|
3134
|
+
* @param store - The store to search
|
|
3135
|
+
* @param namespace - Hierarchical path prefix to search within
|
|
3136
|
+
* @param options - Optional query, filter, and page_size
|
|
3137
|
+
* @returns List of all items matching the search criteria
|
|
3138
|
+
*/
|
|
3139
|
+
private searchStorePaginated;
|
|
3140
|
+
/**
|
|
3141
|
+
* List files and directories in the specified directory (non-recursive).
|
|
3142
|
+
*
|
|
3143
|
+
* @param path - Absolute path to directory
|
|
3144
|
+
* @returns List of FileInfo objects for files and directories directly in the directory.
|
|
3145
|
+
* Directories have a trailing / in their path and is_dir=true.
|
|
3146
|
+
*/
|
|
3147
|
+
lsInfo(path: string): Promise<FileInfo[]>;
|
|
3148
|
+
/**
|
|
3149
|
+
* Read file content with line numbers.
|
|
3150
|
+
*
|
|
3151
|
+
* @param filePath - Absolute file path
|
|
3152
|
+
* @param offset - Line offset to start reading from (0-indexed)
|
|
3153
|
+
* @param limit - Maximum number of lines to read
|
|
3154
|
+
* @returns Formatted file content with line numbers, or error message
|
|
3155
|
+
*/
|
|
3156
|
+
read(filePath: string, offset?: number, limit?: number): Promise<string>;
|
|
3157
|
+
/**
|
|
3158
|
+
* Read file content as raw FileData.
|
|
3159
|
+
*
|
|
3160
|
+
* @param filePath - Absolute file path
|
|
3161
|
+
* @returns Raw file content as FileData
|
|
3162
|
+
*/
|
|
3163
|
+
readRaw(filePath: string): Promise<FileData>;
|
|
3164
|
+
/**
|
|
3165
|
+
* Create a new file with content.
|
|
3166
|
+
* Returns WriteResult. External storage sets filesUpdate=null.
|
|
3167
|
+
*/
|
|
3168
|
+
write(filePath: string, content: string): Promise<WriteResult>;
|
|
3169
|
+
/**
|
|
3170
|
+
* Edit a file by replacing string occurrences.
|
|
3171
|
+
* Returns EditResult. External storage sets filesUpdate=null.
|
|
3172
|
+
*/
|
|
3173
|
+
edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult>;
|
|
3174
|
+
/**
|
|
3175
|
+
* Structured search results or error string for invalid input.
|
|
3176
|
+
*/
|
|
3177
|
+
grepRaw(pattern: string, path?: string, glob?: string | null): Promise<GrepMatch[] | string>;
|
|
3178
|
+
/**
|
|
3179
|
+
* Structured glob matching returning FileInfo objects.
|
|
3180
|
+
*/
|
|
3181
|
+
globInfo(pattern: string, path?: string): Promise<FileInfo[]>;
|
|
3182
|
+
}
|
|
3183
|
+
|
|
3184
|
+
/**
|
|
3185
|
+
* FilesystemBackend: Read and write files directly from the filesystem.
|
|
3186
|
+
*
|
|
3187
|
+
* Security and search upgrades:
|
|
3188
|
+
* - Secure path resolution with root containment when in virtual_mode (sandboxed to cwd)
|
|
3189
|
+
* - Prevent symlink-following on file I/O using O_NOFOLLOW when available
|
|
3190
|
+
* - Ripgrep-powered grep with JSON parsing, plus regex fallback
|
|
3191
|
+
* and optional glob include filtering, while preserving virtual path behavior
|
|
3192
|
+
*/
|
|
3193
|
+
|
|
3194
|
+
/**
|
|
3195
|
+
* Backend that reads and writes files directly from the filesystem.
|
|
3196
|
+
*
|
|
3197
|
+
* Files are accessed using their actual filesystem paths. Relative paths are
|
|
3198
|
+
* resolved relative to the current working directory. Content is read/written
|
|
3199
|
+
* as plain text, and metadata (timestamps) are derived from filesystem stats.
|
|
3200
|
+
*/
|
|
3201
|
+
declare class FilesystemBackend implements BackendProtocol {
|
|
3202
|
+
private cwd;
|
|
3203
|
+
private virtualMode;
|
|
3204
|
+
private maxFileSizeBytes;
|
|
3205
|
+
constructor(options?: {
|
|
3206
|
+
rootDir?: string;
|
|
3207
|
+
virtualMode?: boolean;
|
|
3208
|
+
maxFileSizeMb?: number;
|
|
3209
|
+
});
|
|
3210
|
+
/**
|
|
3211
|
+
* Resolve a file path with security checks.
|
|
3212
|
+
*
|
|
3213
|
+
* When virtualMode=true, treat incoming paths as virtual absolute paths under
|
|
3214
|
+
* this.cwd, disallow traversal (.., ~) and ensure resolved path stays within root.
|
|
3215
|
+
* When virtualMode=false, preserve legacy behavior: absolute paths are allowed
|
|
3216
|
+
* as-is; relative paths resolve under cwd.
|
|
3217
|
+
*
|
|
3218
|
+
* @param key - File path (absolute, relative, or virtual when virtualMode=true)
|
|
3219
|
+
* @returns Resolved absolute path string
|
|
3220
|
+
* @throws Error if path traversal detected or path outside root
|
|
3221
|
+
*/
|
|
3222
|
+
private resolvePath;
|
|
3223
|
+
/**
|
|
3224
|
+
* List files and directories in the specified directory (non-recursive).
|
|
3225
|
+
*
|
|
3226
|
+
* @param dirPath - Absolute directory path to list files from
|
|
3227
|
+
* @returns List of FileInfo objects for files and directories directly in the directory.
|
|
3228
|
+
* Directories have a trailing / in their path and is_dir=true.
|
|
3229
|
+
*/
|
|
3230
|
+
lsInfo(dirPath: string): Promise<FileInfo[]>;
|
|
3231
|
+
/**
|
|
3232
|
+
* Read file content with line numbers.
|
|
3233
|
+
*
|
|
3234
|
+
* @param filePath - Absolute or relative file path
|
|
3235
|
+
* @param offset - Line offset to start reading from (0-indexed)
|
|
3236
|
+
* @param limit - Maximum number of lines to read
|
|
3237
|
+
* @returns Formatted file content with line numbers, or error message
|
|
3238
|
+
*/
|
|
3239
|
+
read(filePath: string, offset?: number, limit?: number): Promise<string>;
|
|
3240
|
+
/**
|
|
3241
|
+
* Read file content as raw FileData.
|
|
3242
|
+
*
|
|
3243
|
+
* @param filePath - Absolute file path
|
|
3244
|
+
* @returns Raw file content as FileData
|
|
3245
|
+
*/
|
|
3246
|
+
readRaw(filePath: string): Promise<FileData>;
|
|
3247
|
+
/**
|
|
3248
|
+
* Create a new file with content.
|
|
3249
|
+
* Returns WriteResult. External storage sets filesUpdate=null.
|
|
3250
|
+
*/
|
|
3251
|
+
write(filePath: string, content: string): Promise<WriteResult>;
|
|
3252
|
+
/**
|
|
3253
|
+
* Edit a file by replacing string occurrences.
|
|
3254
|
+
* Returns EditResult. External storage sets filesUpdate=null.
|
|
3255
|
+
*/
|
|
3256
|
+
edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult>;
|
|
3257
|
+
/**
|
|
3258
|
+
* Structured search results or error string for invalid input.
|
|
3259
|
+
*/
|
|
3260
|
+
grepRaw(pattern: string, dirPath?: string, glob?: string | null): Promise<GrepMatch[] | string>;
|
|
3261
|
+
/**
|
|
3262
|
+
* Try to use ripgrep for fast searching.
|
|
3263
|
+
* Returns null if ripgrep is not available or fails.
|
|
3264
|
+
*/
|
|
3265
|
+
private ripgrepSearch;
|
|
3266
|
+
/**
|
|
3267
|
+
* Fallback regex search implementation.
|
|
3268
|
+
*/
|
|
3269
|
+
private pythonSearch;
|
|
3270
|
+
/**
|
|
3271
|
+
* Structured glob matching returning FileInfo objects.
|
|
3272
|
+
*/
|
|
3273
|
+
globInfo(pattern: string, searchPath?: string): Promise<FileInfo[]>;
|
|
3274
|
+
}
|
|
3275
|
+
|
|
3276
|
+
/**
|
|
3277
|
+
* CompositeBackend: Route operations to different backends based on path prefix.
|
|
3278
|
+
*/
|
|
3279
|
+
|
|
3280
|
+
/**
|
|
3281
|
+
* Backend that routes file operations to different backends based on path prefix.
|
|
3282
|
+
*
|
|
3283
|
+
* This enables hybrid storage strategies like:
|
|
3284
|
+
* - `/memories/` → StoreBackend (persistent, cross-thread)
|
|
3285
|
+
* - Everything else → StateBackend (ephemeral, per-thread)
|
|
3286
|
+
*
|
|
3287
|
+
* The CompositeBackend handles path prefix stripping/re-adding transparently.
|
|
3288
|
+
*/
|
|
3289
|
+
declare class CompositeBackend implements BackendProtocol {
|
|
3290
|
+
private default;
|
|
3291
|
+
private routes;
|
|
3292
|
+
private sortedRoutes;
|
|
3293
|
+
constructor(defaultBackend: BackendProtocol, routes: Record<string, BackendProtocol>);
|
|
3294
|
+
/**
|
|
3295
|
+
* Determine which backend handles this key and strip prefix.
|
|
3296
|
+
*
|
|
3297
|
+
* @param key - Original file path
|
|
3298
|
+
* @returns Tuple of [backend, stripped_key] where stripped_key has the route
|
|
3299
|
+
* prefix removed (but keeps leading slash).
|
|
3300
|
+
*/
|
|
3301
|
+
private getBackendAndKey;
|
|
3302
|
+
/**
|
|
3303
|
+
* List files and directories in the specified directory (non-recursive).
|
|
3304
|
+
*
|
|
3305
|
+
* @param path - Absolute path to directory
|
|
3306
|
+
* @returns List of FileInfo objects with route prefixes added, for files and directories
|
|
3307
|
+
* directly in the directory. Directories have a trailing / in their path and is_dir=true.
|
|
3308
|
+
*/
|
|
3309
|
+
lsInfo(path: string): Promise<FileInfo[]>;
|
|
3310
|
+
/**
|
|
3311
|
+
* Read file content, routing to appropriate backend.
|
|
3312
|
+
*
|
|
3313
|
+
* @param filePath - Absolute file path
|
|
3314
|
+
* @param offset - Line offset to start reading from (0-indexed)
|
|
3315
|
+
* @param limit - Maximum number of lines to read
|
|
3316
|
+
* @returns Formatted file content with line numbers, or error message
|
|
3317
|
+
*/
|
|
3318
|
+
read(filePath: string, offset?: number, limit?: number): Promise<string>;
|
|
3319
|
+
/**
|
|
3320
|
+
* Read file content as raw FileData.
|
|
3321
|
+
*
|
|
3322
|
+
* @param filePath - Absolute file path
|
|
3323
|
+
* @returns Raw file content as FileData
|
|
3324
|
+
*/
|
|
3325
|
+
readRaw(filePath: string): Promise<FileData>;
|
|
3326
|
+
/**
|
|
3327
|
+
* Structured search results or error string for invalid input.
|
|
3328
|
+
*/
|
|
3329
|
+
grepRaw(pattern: string, path?: string, glob?: string | null): Promise<GrepMatch[] | string>;
|
|
3330
|
+
/**
|
|
3331
|
+
* Structured glob matching returning FileInfo objects.
|
|
3332
|
+
*/
|
|
3333
|
+
globInfo(pattern: string, path?: string): Promise<FileInfo[]>;
|
|
3334
|
+
/**
|
|
3335
|
+
* Create a new file, routing to appropriate backend.
|
|
3336
|
+
*
|
|
3337
|
+
* @param filePath - Absolute file path
|
|
3338
|
+
* @param content - File content as string
|
|
3339
|
+
* @returns WriteResult with path or error
|
|
3340
|
+
*/
|
|
3341
|
+
write(filePath: string, content: string): Promise<WriteResult>;
|
|
3342
|
+
/**
|
|
3343
|
+
* Edit a file, routing to appropriate backend.
|
|
3344
|
+
*
|
|
3345
|
+
* @param filePath - Absolute file path
|
|
3346
|
+
* @param oldString - String to find and replace
|
|
3347
|
+
* @param newString - Replacement string
|
|
3348
|
+
* @param replaceAll - If true, replace all occurrences
|
|
3349
|
+
* @returns EditResult with path, occurrences, or error
|
|
3350
|
+
*/
|
|
3351
|
+
edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult>;
|
|
3352
|
+
}
|
|
3353
|
+
|
|
3354
|
+
/**
|
|
3355
|
+
* MemoryBackend: In-memory file storage backend.
|
|
3356
|
+
*
|
|
3357
|
+
* Stores files in a shared Map instance. Useful for sharing file state
|
|
3358
|
+
* across multiple agents within the same process (e.g., team members).
|
|
3359
|
+
*
|
|
3360
|
+
* All operations are synchronous and use in-memory storage.
|
|
3361
|
+
*/
|
|
3362
|
+
|
|
3363
|
+
declare class MemoryBackend implements BackendProtocol {
|
|
3364
|
+
private files;
|
|
3365
|
+
constructor(files?: Map<string, FileData>);
|
|
3366
|
+
private getFiles;
|
|
3367
|
+
lsInfo(path: string): FileInfo[];
|
|
3368
|
+
read(filePath: string, offset?: number, limit?: number): string;
|
|
3369
|
+
readRaw(filePath: string): FileData;
|
|
3370
|
+
write(filePath: string, content: string): WriteResult;
|
|
3371
|
+
edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): EditResult;
|
|
3372
|
+
grepRaw(pattern: string, path?: string, glob?: string | null): GrepMatch[] | string;
|
|
3373
|
+
globInfo(pattern: string, path?: string): FileInfo[];
|
|
3374
|
+
}
|
|
3375
|
+
|
|
3376
|
+
/**
|
|
3377
|
+
* SandboxFilesystem: A sandboxed filesystem backend that connects to a remote sandbox via SDK.
|
|
3378
|
+
*
|
|
3379
|
+
* This backend provides a secure, isolated filesystem environment by connecting to a remote
|
|
3380
|
+
* sandbox service through the @agent-infra/sandbox SDK. It implements the BackendProtocol
|
|
3381
|
+
* interface and delegates all file operations to the remote sandbox.
|
|
3382
|
+
*
|
|
3383
|
+
* Features:
|
|
3384
|
+
* - Remote sandbox connection via HTTP API
|
|
3385
|
+
* - Virtual path support (all paths start with /)
|
|
3386
|
+
* - Path traversal prevention
|
|
3387
|
+
* - Full BackendProtocol implementation
|
|
3388
|
+
*/
|
|
3389
|
+
|
|
3390
|
+
/**
|
|
3391
|
+
* Sandboxed filesystem backend that connects to a remote sandbox service.
|
|
3392
|
+
*
|
|
3393
|
+
* All file operations are delegated to the remote sandbox via the SDK.
|
|
3394
|
+
* Paths are treated as virtual absolute paths (starting with /).
|
|
3395
|
+
*/
|
|
3396
|
+
declare class SandboxFilesystem implements BackendProtocol {
|
|
3397
|
+
private sandbox;
|
|
3398
|
+
private maxFileSizeBytes;
|
|
3399
|
+
private workingDirectory;
|
|
3400
|
+
private baseURL;
|
|
3401
|
+
private homeDir;
|
|
3402
|
+
/**
|
|
3403
|
+
* Create a new SandboxFilesystem instance.
|
|
3404
|
+
*
|
|
3405
|
+
* @param options - Configuration options
|
|
3406
|
+
* @param options.baseURL - Base URL of the sandbox service (default: 'http://localhost:8080')
|
|
3407
|
+
* @param options.maxFileSizeMb - Maximum file size in MB (default: 10)
|
|
3408
|
+
* @param options.sandboxInstance - Optional Sandbox instance (if provided, baseURL is ignored)
|
|
3409
|
+
*/
|
|
3410
|
+
constructor(options?: {
|
|
3411
|
+
baseURL?: string;
|
|
3412
|
+
workingDirectory?: string;
|
|
3413
|
+
maxFileSizeMb?: number;
|
|
3414
|
+
sandboxInstance?: SandboxClient;
|
|
3415
|
+
});
|
|
3416
|
+
private resolvePath;
|
|
3417
|
+
/**
|
|
3418
|
+
* Convert a real filesystem path to a virtual path.
|
|
3419
|
+
*
|
|
3420
|
+
* @param realPath - Real filesystem path
|
|
3421
|
+
* @returns Virtual path starting with /
|
|
3422
|
+
*/
|
|
3423
|
+
private toVirtualPath;
|
|
3424
|
+
/**
|
|
3425
|
+
* List files and directories in the specified directory (non-recursive).
|
|
3426
|
+
*
|
|
3427
|
+
* @param dirPath - Virtual directory path (must start with /)
|
|
3428
|
+
* @returns List of FileInfo objects for files and directories directly in the directory.
|
|
3429
|
+
* Directories have a trailing / in their path and is_dir=true.
|
|
3430
|
+
*/
|
|
3431
|
+
lsInfo(dirPath: string): Promise<FileInfo[]>;
|
|
3432
|
+
/**
|
|
3433
|
+
* Read file content with line numbers.
|
|
3434
|
+
*
|
|
3435
|
+
* @param filePath - Virtual file path (must start with /)
|
|
3436
|
+
* @param offset - Line offset to start reading from (0-indexed)
|
|
3437
|
+
* @param limit - Maximum number of lines to read
|
|
3438
|
+
* @returns Formatted file content with line numbers, or error message
|
|
3439
|
+
*/
|
|
3440
|
+
read(filePath: string, offset?: number, limit?: number): Promise<string>;
|
|
3441
|
+
/**
|
|
3442
|
+
* Read file content as raw FileData.
|
|
3443
|
+
*
|
|
3444
|
+
* @param filePath - Virtual file path (must start with /)
|
|
3445
|
+
* @returns Raw file content as FileData
|
|
3446
|
+
*/
|
|
3447
|
+
readRaw(filePath: string): Promise<FileData>;
|
|
3448
|
+
/**
|
|
3449
|
+
* Create a new file with content.
|
|
3450
|
+
* Returns WriteResult. External storage sets filesUpdate=null.
|
|
3451
|
+
*
|
|
3452
|
+
* @param filePath - Virtual file path (must start with /)
|
|
3453
|
+
* @param content - File content as string
|
|
3454
|
+
* @returns WriteResult with error populated on failure
|
|
3455
|
+
*/
|
|
3456
|
+
write(filePath: string, content: string): Promise<WriteResult>;
|
|
3457
|
+
/**
|
|
3458
|
+
* Edit a file by replacing string occurrences.
|
|
3459
|
+
* Returns EditResult. External storage sets filesUpdate=null.
|
|
3460
|
+
*
|
|
3461
|
+
* @param filePath - Virtual file path (must start with /)
|
|
3462
|
+
* @param oldString - String to find and replace
|
|
3463
|
+
* @param newString - Replacement string
|
|
3464
|
+
* @param replaceAll - If true, replace all occurrences (default: false)
|
|
3465
|
+
* @returns EditResult with error, path, filesUpdate, and occurrences
|
|
3466
|
+
*/
|
|
3467
|
+
edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult>;
|
|
3468
|
+
/**
|
|
3469
|
+
* Structured search results or error string for invalid input.
|
|
3470
|
+
*
|
|
3471
|
+
* Searches file contents for a regex pattern within the sandbox.
|
|
3472
|
+
*
|
|
3473
|
+
* @param pattern - Regex pattern to search for
|
|
3474
|
+
* @param searchPath - Base path to search from (default: "/")
|
|
3475
|
+
* @param glob - Optional glob pattern to filter files (e.g., "*.py")
|
|
3476
|
+
* @returns List of GrepMatch objects or error string for invalid regex
|
|
3477
|
+
*/
|
|
3478
|
+
grepRaw(pattern: string, searchPath?: string | null, glob?: string | null): Promise<GrepMatch[] | string>;
|
|
3479
|
+
/**
|
|
3480
|
+
* Structured glob matching returning FileInfo objects.
|
|
3481
|
+
*
|
|
3482
|
+
* @param pattern - Glob pattern (e.g., `*.py`, `**\/*.ts`)
|
|
3483
|
+
* @param searchPath - Base path to search from (default: "/")
|
|
3484
|
+
* @returns List of FileInfo objects matching the pattern
|
|
3485
|
+
*/
|
|
3486
|
+
globInfo(pattern: string, searchPath?: string): Promise<FileInfo[]>;
|
|
3487
|
+
}
|
|
3488
|
+
|
|
3489
|
+
/**
|
|
3490
|
+
* Shared utility functions for memory backend implementations.
|
|
3491
|
+
*
|
|
3492
|
+
* This module contains both user-facing string formatters and structured
|
|
3493
|
+
* helpers used by backends and the composite router. Structured helpers
|
|
3494
|
+
* enable composition without fragile string parsing.
|
|
3495
|
+
*/
|
|
3496
|
+
|
|
3497
|
+
declare const EMPTY_CONTENT_WARNING = "System reminder: File exists but has empty contents";
|
|
3498
|
+
declare const MAX_LINE_LENGTH = 10000;
|
|
3499
|
+
declare const LINE_NUMBER_WIDTH = 6;
|
|
3500
|
+
declare const TOOL_RESULT_TOKEN_LIMIT = 20000;
|
|
3501
|
+
declare const TRUNCATION_GUIDANCE = "... [results truncated, try being more specific with your parameters]";
|
|
3502
|
+
/**
|
|
3503
|
+
* Sanitize tool_call_id to prevent path traversal and separator issues.
|
|
3504
|
+
*
|
|
3505
|
+
* Replaces dangerous characters (., /, \) with underscores.
|
|
3506
|
+
*/
|
|
3507
|
+
declare function sanitizeToolCallId(toolCallId: string): string;
|
|
3508
|
+
/**
|
|
3509
|
+
* Format file content with line numbers (cat -n style).
|
|
3510
|
+
*
|
|
3511
|
+
* Chunks lines longer than MAX_LINE_LENGTH with continuation markers (e.g., 5.1, 5.2).
|
|
3512
|
+
*
|
|
3513
|
+
* @param content - File content as string or list of lines
|
|
3514
|
+
* @param startLine - Starting line number (default: 1)
|
|
3515
|
+
* @returns Formatted content with line numbers and continuation markers
|
|
3516
|
+
*/
|
|
3517
|
+
declare function formatContentWithLineNumbers(content: string | string[], startLine?: number): string;
|
|
3518
|
+
/**
|
|
3519
|
+
* Check if content is empty and return warning message.
|
|
3520
|
+
*
|
|
3521
|
+
* @param content - Content to check
|
|
3522
|
+
* @returns Warning message if empty, null otherwise
|
|
3523
|
+
*/
|
|
3524
|
+
declare function checkEmptyContent(content: string): string | null;
|
|
3525
|
+
/**
|
|
3526
|
+
* Convert FileData to plain string content.
|
|
3527
|
+
*
|
|
3528
|
+
* @param fileData - FileData object with 'content' key
|
|
3529
|
+
* @returns Content as string with lines joined by newlines
|
|
3530
|
+
*/
|
|
3531
|
+
declare function fileDataToString(fileData: FileData): string;
|
|
3532
|
+
/**
|
|
3533
|
+
* Create a FileData object with timestamps.
|
|
3534
|
+
*
|
|
3535
|
+
* @param content - File content as string
|
|
3536
|
+
* @param createdAt - Optional creation timestamp (ISO format)
|
|
3537
|
+
* @returns FileData object with content and timestamps
|
|
3538
|
+
*/
|
|
3539
|
+
declare function createFileData(content: string, createdAt?: string): FileData;
|
|
3540
|
+
/**
|
|
3541
|
+
* Update FileData with new content, preserving creation timestamp.
|
|
3542
|
+
*
|
|
3543
|
+
* @param fileData - Existing FileData object
|
|
3544
|
+
* @param content - New content as string
|
|
3545
|
+
* @returns Updated FileData object
|
|
3546
|
+
*/
|
|
3547
|
+
declare function updateFileData(fileData: FileData, content: string): FileData;
|
|
3548
|
+
/**
|
|
3549
|
+
* Format file data for read response with line numbers.
|
|
3550
|
+
*
|
|
3551
|
+
* @param fileData - FileData object
|
|
3552
|
+
* @param offset - Line offset (0-indexed)
|
|
3553
|
+
* @param limit - Maximum number of lines
|
|
3554
|
+
* @returns Formatted content or error message
|
|
3555
|
+
*/
|
|
3556
|
+
declare function formatReadResponse(fileData: FileData, offset: number, limit: number): string;
|
|
3557
|
+
/**
|
|
3558
|
+
* Perform string replacement with occurrence validation.
|
|
3559
|
+
*
|
|
3560
|
+
* @param content - Original content
|
|
3561
|
+
* @param oldString - String to replace
|
|
3562
|
+
* @param newString - Replacement string
|
|
3563
|
+
* @param replaceAll - Whether to replace all occurrences
|
|
3564
|
+
* @returns Tuple of [new_content, occurrences] on success, or error message string
|
|
3565
|
+
*/
|
|
3566
|
+
declare function performStringReplacement(content: string, oldString: string, newString: string, replaceAll: boolean): [string, number] | string;
|
|
3567
|
+
/**
|
|
3568
|
+
* Truncate list or string result if it exceeds token limit (rough estimate: 4 chars/token).
|
|
3569
|
+
*/
|
|
3570
|
+
declare function truncateIfTooLong(result: string[] | string): string[] | string;
|
|
3571
|
+
/**
|
|
3572
|
+
* Validate and normalize a path.
|
|
3573
|
+
*
|
|
3574
|
+
* @param path - Path to validate
|
|
3575
|
+
* @returns Normalized path starting with / and ending with /
|
|
3576
|
+
* @throws Error if path is invalid
|
|
3577
|
+
*/
|
|
3578
|
+
declare function validatePath(path: string | null | undefined): string;
|
|
3579
|
+
/**
|
|
3580
|
+
* Search files dict for paths matching glob pattern.
|
|
3581
|
+
*
|
|
3582
|
+
* @param files - Dictionary of file paths to FileData
|
|
3583
|
+
* @param pattern - Glob pattern (e.g., `*.py`, `**\/*.ts`)
|
|
3584
|
+
* @param path - Base path to search from
|
|
3585
|
+
* @returns Newline-separated file paths, sorted by modification time (most recent first).
|
|
3586
|
+
* Returns "No files found" if no matches.
|
|
3587
|
+
*
|
|
3588
|
+
* @example
|
|
3589
|
+
* ```typescript
|
|
3590
|
+
* const files = {"/src/main.py": FileData(...), "/test.py": FileData(...)};
|
|
3591
|
+
* globSearchFiles(files, "*.py", "/");
|
|
3592
|
+
* // Returns: "/test.py\n/src/main.py" (sorted by modified_at)
|
|
3593
|
+
* ```
|
|
3594
|
+
*/
|
|
3595
|
+
declare function globSearchFiles(files: Record<string, FileData>, pattern: string, path?: string): string;
|
|
3596
|
+
/**
|
|
3597
|
+
* Format grep search results based on output mode.
|
|
3598
|
+
*
|
|
3599
|
+
* @param results - Dictionary mapping file paths to list of [line_num, line_content] tuples
|
|
3600
|
+
* @param outputMode - Output format - "files_with_matches", "content", or "count"
|
|
3601
|
+
* @returns Formatted string output
|
|
3602
|
+
*/
|
|
3603
|
+
declare function formatGrepResults(results: Record<string, Array<[number, string]>>, outputMode: "files_with_matches" | "content" | "count"): string;
|
|
3604
|
+
/**
|
|
3605
|
+
* Search file contents for regex pattern.
|
|
3606
|
+
*
|
|
3607
|
+
* @param files - Dictionary of file paths to FileData
|
|
3608
|
+
* @param pattern - Regex pattern to search for
|
|
3609
|
+
* @param path - Base path to search from
|
|
3610
|
+
* @param glob - Optional glob pattern to filter files (e.g., "*.py")
|
|
3611
|
+
* @param outputMode - Output format - "files_with_matches", "content", or "count"
|
|
3612
|
+
* @returns Formatted search results. Returns "No matches found" if no results.
|
|
3613
|
+
*
|
|
3614
|
+
* @example
|
|
3615
|
+
* ```typescript
|
|
3616
|
+
* const files = {"/file.py": FileData({content: ["import os", "print('hi')"], ...})};
|
|
3617
|
+
* grepSearchFiles(files, "import", "/");
|
|
3618
|
+
* // Returns: "/file.py" (with output_mode="files_with_matches")
|
|
3619
|
+
* ```
|
|
3620
|
+
*/
|
|
3621
|
+
declare function grepSearchFiles(files: Record<string, FileData>, pattern: string, path?: string | null, glob?: string | null, outputMode?: "files_with_matches" | "content" | "count"): string;
|
|
3622
|
+
/**
|
|
3623
|
+
* Return structured grep matches from an in-memory files mapping.
|
|
3624
|
+
*
|
|
3625
|
+
* Returns a list of GrepMatch on success, or a string for invalid inputs
|
|
3626
|
+
* (e.g., invalid regex). We deliberately do not raise here to keep backends
|
|
3627
|
+
* non-throwing in tool contexts and preserve user-facing error messages.
|
|
3628
|
+
*/
|
|
3629
|
+
declare function grepMatchesFromFiles(files: Record<string, FileData>, pattern: string, path?: string | null, glob?: string | null): GrepMatch[] | string;
|
|
3630
|
+
/**
|
|
3631
|
+
* Group structured matches into the legacy dict form used by formatters.
|
|
3632
|
+
*/
|
|
3633
|
+
declare function buildGrepResultsDict(matches: GrepMatch[]): Record<string, Array<[number, string]>>;
|
|
3634
|
+
/**
|
|
3635
|
+
* Format structured grep matches using existing formatting logic.
|
|
3636
|
+
*/
|
|
3637
|
+
declare function formatGrepMatches(matches: GrepMatch[], outputMode: "files_with_matches" | "content" | "count"): string;
|
|
3638
|
+
|
|
3639
|
+
/**
|
|
3640
|
+
* Event bus service
|
|
3641
|
+
* Used for event publishing and subscription between internal system components
|
|
3642
|
+
*/
|
|
3643
|
+
declare class EventBus {
|
|
3644
|
+
private emitter;
|
|
3645
|
+
private defaultQueueKey;
|
|
3646
|
+
constructor();
|
|
3647
|
+
/**
|
|
3648
|
+
* Set the default queue key for queue operations
|
|
3649
|
+
* @param queueKey Queue key name
|
|
3650
|
+
*/
|
|
3651
|
+
setDefaultQueueKey(queueKey: string): void;
|
|
3652
|
+
/**
|
|
3653
|
+
* Publish event
|
|
3654
|
+
* @param eventName Event name
|
|
3655
|
+
* @param data Event data
|
|
3656
|
+
* @param useQueue Whether to use queue for publishing
|
|
3657
|
+
*/
|
|
3658
|
+
publish(eventName: string, data: any, useQueue?: boolean): void;
|
|
3659
|
+
/**
|
|
3660
|
+
* Subscribe to event
|
|
3661
|
+
* @param eventName Event name
|
|
3662
|
+
* @param callback Callback function
|
|
3663
|
+
*/
|
|
3664
|
+
subscribe(eventName: string, callback: (data: any) => void): void;
|
|
3665
|
+
/**
|
|
3666
|
+
* Unsubscribe from event
|
|
3667
|
+
* @param eventName Event name
|
|
3668
|
+
* @param callback Callback function
|
|
3669
|
+
*/
|
|
3670
|
+
unsubscribe(eventName: string, callback: (data: any) => void): void;
|
|
3671
|
+
/**
|
|
3672
|
+
* Subscribe to event once
|
|
3673
|
+
* @param eventName Event name
|
|
3674
|
+
* @param callback Callback function
|
|
3675
|
+
*/
|
|
3676
|
+
subscribeOnce(eventName: string, callback: (data: any) => void): void;
|
|
3677
|
+
}
|
|
3678
|
+
declare const eventBus: EventBus;
|
|
3679
|
+
|
|
3680
|
+
declare class AgentManager {
|
|
3681
|
+
private static instance;
|
|
3682
|
+
private constructor();
|
|
3683
|
+
private agents;
|
|
3684
|
+
static getInstance(): AgentManager;
|
|
3685
|
+
callAgentInQueue(queue: {
|
|
3686
|
+
assistant_id: string;
|
|
3687
|
+
input?: any;
|
|
3688
|
+
thread_id: string;
|
|
3689
|
+
command?: any;
|
|
3690
|
+
"x-tenant-id"?: string;
|
|
3691
|
+
}, return_agent_state?: boolean): Promise<unknown>;
|
|
3692
|
+
}
|
|
3693
|
+
|
|
3694
|
+
declare const AGENT_TASK_EVENT = "agent:execute";
|
|
3695
|
+
|
|
3696
|
+
/**
|
|
3697
|
+
* 全局加密工具
|
|
3698
|
+
* 用于敏感数据加密存储(如数据库密码、API 密钥等)
|
|
3699
|
+
*
|
|
3700
|
+
* @module @axiom-lattice/core/util/encryption
|
|
3701
|
+
*/
|
|
3702
|
+
/**
|
|
3703
|
+
* 获取加密密钥
|
|
3704
|
+
* 优先从环境变量读取,否则使用默认值
|
|
3705
|
+
* @returns 32 字节的 Buffer 密钥
|
|
3706
|
+
*/
|
|
3707
|
+
declare function getEncryptionKey(): Buffer;
|
|
3708
|
+
/**
|
|
3709
|
+
* 加密字符串
|
|
3710
|
+
* @param plaintext 明文字符串
|
|
3711
|
+
* @param key 可选的加密密钥,默认使用全局密钥
|
|
3712
|
+
* @returns 加密后的字符串 (salt:iv:ciphertext:authTag 的 base64 编码)
|
|
3713
|
+
*/
|
|
3714
|
+
declare function encrypt(plaintext: string, key?: Buffer): string;
|
|
3715
|
+
/**
|
|
3716
|
+
* 解密字符串
|
|
3717
|
+
* @param encrypted 加密的字符串 (base64 编码)
|
|
3718
|
+
* @param key 可选的解密密钥,默认使用全局密钥
|
|
3719
|
+
* @returns 解密后的明文
|
|
3720
|
+
* @throws 如果解密失败(密钥错误或数据损坏)
|
|
3721
|
+
*/
|
|
3722
|
+
declare function decrypt(encrypted: string, key?: Buffer): string;
|
|
3723
|
+
/**
|
|
3724
|
+
* 检查是否使用默认密钥
|
|
3725
|
+
* @returns 如果使用默认密钥返回 true
|
|
3726
|
+
*/
|
|
3727
|
+
declare function isUsingDefaultKey(): boolean;
|
|
3728
|
+
/**
|
|
3729
|
+
* 验证加密密钥
|
|
3730
|
+
* 生产环境未设置 LATTICE_ENCRYPTION_KEY 时会抛出错误
|
|
3731
|
+
* 开发环境仅输出警告
|
|
3732
|
+
*/
|
|
3733
|
+
declare function validateEncryptionKey(): void;
|
|
3734
|
+
/**
|
|
3735
|
+
* 清除缓存的密钥(用于测试或重新加载配置)
|
|
3736
|
+
*/
|
|
3737
|
+
declare function clearEncryptionKeyCache(): void;
|
|
2165
3738
|
|
|
2166
|
-
export { AGENT_TASK_EVENT, type AgentClient, type AgentLattice, AgentLatticeManager, AgentManager, type BufferStats, type Chunk, ChunkBuffer, ChunkBufferLatticeManager, type ColumnInfo, ConsoleLoggerClient, type CronFields, type DatabaseConfig, type DatabaseType, DefaultScheduleClient, type EmbeddingsLatticeInterface, EmbeddingsLatticeManager, FileSystemSkillStore, type FileSystemSkillStoreOptions, type ISqlDatabase, InMemoryAssistantStore, InMemoryChunkBuffer, InMemoryThreadStore, type IsolatedLevel, type LoggerLattice, LoggerLatticeManager, type McpLatticeInterface, McpLatticeManager, type McpServerInfo, MemoryLatticeManager, MemoryQueueClient, MemoryScheduleStorage, type ModelConfig, type ModelLatticeInterface, ModelLatticeManager, PinoLoggerClient, PostgresDatabase, type QueryResult, type QueueLattice, QueueLatticeManager, type RunSandboxConfig, SandboxLatticeManager, type SandboxManagerProtocol, type ScheduleLattice, ScheduleLatticeManager, type SkillLattice, SkillLatticeManager, SqlDatabaseManager, type StoreLattice, StoreLatticeManager, type StoreType, type StoreTypeMap, type TableInfo, type TableSchema, type ThreadBuffer, type ThreadBufferConfig, ThreadStatus, type ToolDefinition, type ToolLattice, ToolLatticeManager, type VectorStoreLatticeInterface, VectorStoreLatticeManager, agentLatticeManager, createInfoSqlTool, createListTablesSqlTool, createQueryCheckerSqlTool, createQuerySqlTool, describeCronExpression, embeddingsLatticeManager, eventBus, eventBus as eventBusDefault, getAgentClient, getAgentConfig, getAgentLattice, getAllAgentConfigs, getAllToolDefinitions, getCheckpointSaver, getChunkBuffer, getEmbeddingsClient, getEmbeddingsLattice, getLoggerLattice, getModelLattice, getNextCronTime, getQueueLattice, getSandBoxManager, getScheduleLattice, getStoreLattice, getToolClient, getToolDefinition, getToolLattice, getVectorStoreClient, getVectorStoreLattice, hasChunkBuffer, isValidCronExpression, isValidSandboxName, isValidSkillName, loggerLatticeManager, mcpManager, modelLatticeManager, normalizeSandboxName, parseCronExpression, queueLatticeManager, registerAgentLattice, registerAgentLattices, registerCheckpointSaver, registerChunkBuffer, registerEmbeddingsLattice, registerExistingTool, registerLoggerLattice, registerModelLattice, registerQueueLattice, registerScheduleLattice, registerStoreLattice, registerToolLattice, registerVectorStoreLattice, sandboxLatticeManager, scheduleLatticeManager, skillLatticeManager, sqlDatabaseManager, storeLatticeManager, toolLatticeManager, validateAgentInput, validateSkillName, validateToolInput, vectorStoreLatticeManager };
|
|
3739
|
+
export { AGENT_TASK_EVENT, type AgentClient, type AgentLattice, AgentLatticeManager, AgentManager, type BackendFactory, type BackendProtocol, type BufferStats, type Chunk, ChunkBuffer, ChunkBufferLatticeManager, type ColumnInfo, CompositeBackend, ConsoleLoggerClient, type CronFields, type DatabaseConfig, type DatabaseType, DefaultScheduleClient, EMPTY_CONTENT_WARNING, type EditResult, type EmbeddingsLatticeInterface, EmbeddingsLatticeManager, type FileData, type FileInfo, FileSystemSkillStore, type FileSystemSkillStoreOptions, FilesystemBackend, type GrepMatch, type ISqlDatabase, InMemoryAssistantStore, InMemoryChunkBuffer, InMemoryDatabaseConfigStore, InMemoryMailboxStore, InMemoryTaskListStore, InMemoryThreadStore, type IsolatedLevel, LINE_NUMBER_WIDTH, type LoggerLattice, LoggerLatticeManager, MAX_LINE_LENGTH, type MailboxMessage, type MailboxStore, type McpLatticeInterface, McpLatticeManager, type McpServerInfo, MemoryBackend, MemoryLatticeManager, MemoryQueueClient, MemoryScheduleStorage, MessageType, type ModelConfig, type ModelLatticeInterface, ModelLatticeManager, PinoLoggerClient, PostgresDatabase, type QueryResult, type QueueLattice, QueueLatticeManager, type RunSandboxConfig, SandboxFilesystem, SandboxLatticeManager, type SandboxManagerProtocol, type ScheduleLattice, ScheduleLatticeManager, type SkillLattice, SkillLatticeManager, SqlDatabaseManager, type StateAndStore, StateBackend, StoreBackend, type StoreLattice, StoreLatticeManager, type StoreType, type StoreTypeMap, TOOL_RESULT_TOKEN_LIMIT, TRUNCATION_GUIDANCE, type TableInfo, type TableSchema, type TaskEvent, type TaskListStore, type TaskSpec, TaskStatus, type TaskUpdatable, TeamAgentGraphBuilder, type TeamConfig, type TeamMiddlewareOptions, type TeamTask, type TeammateSpec, type TeammateToolsOptions, type ThreadBuffer, type ThreadBufferConfig, ThreadStatus, type ToolDefinition, type ToolLattice, ToolLatticeManager, type VectorStoreLatticeInterface, VectorStoreLatticeManager, type WriteResult, agentLatticeManager, buildGrepResultsDict, checkEmptyContent, clearEncryptionKeyCache, createAgentTeam, createFileData, createInfoSqlTool, createListTablesSqlTool, createQueryCheckerSqlTool, createQuerySqlTool, createTeamMiddleware, createTeammateTools, decrypt, describeCronExpression, embeddingsLatticeManager, encrypt, eventBus, eventBus as eventBusDefault, fileDataToString, formatContentWithLineNumbers, formatGrepMatches, formatGrepResults, formatReadResponse, getAgentClient, getAgentConfig, getAgentLattice, getAllAgentConfigs, getAllToolDefinitions, getCheckpointSaver, getChunkBuffer, getEmbeddingsClient, getEmbeddingsLattice, getEncryptionKey, getLoggerLattice, getModelLattice, getNextCronTime, getQueueLattice, getSandBoxManager, getScheduleLattice, getStoreLattice, getToolClient, getToolDefinition, getToolLattice, getVectorStoreClient, getVectorStoreLattice, globSearchFiles, grepMatchesFromFiles, grepSearchFiles, hasChunkBuffer, isUsingDefaultKey, isValidCronExpression, isValidSandboxName, isValidSkillName, loggerLatticeManager, mcpManager, modelLatticeManager, normalizeSandboxName, parseCronExpression, performStringReplacement, queueLatticeManager, registerAgentLattice, registerAgentLattices, registerCheckpointSaver, registerChunkBuffer, registerEmbeddingsLattice, registerExistingTool, registerLoggerLattice, registerModelLattice, registerQueueLattice, registerScheduleLattice, registerStoreLattice, registerTeammateAgent, registerToolLattice, registerVectorStoreLattice, sandboxLatticeManager, sanitizeToolCallId, scheduleLatticeManager, skillLatticeManager, sqlDatabaseManager, storeLatticeManager, toolLatticeManager, truncateIfTooLong, unregisterTeammateAgent, updateFileData, validateAgentInput, validateEncryptionKey, validatePath, validateSkillName, validateToolInput, vectorStoreLatticeManager };
|