@24klynx/tools 0.1.0
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 +519 -0
- package/dist/index.d.mts.map +1 -0
- package/dist/index.mjs +5007 -0
- package/dist/index.mjs.map +1 -0
- package/package.json +28 -0
package/dist/index.d.mts
ADDED
|
@@ -0,0 +1,519 @@
|
|
|
1
|
+
//#region src/types.d.ts
|
|
2
|
+
/**
|
|
3
|
+
* Core types for the tool system.
|
|
4
|
+
*
|
|
5
|
+
* Every tool is described by a {@link ToolDescriptor} and handled by
|
|
6
|
+
* a {@link ToolHandler}. The registry maps descriptors to handlers via
|
|
7
|
+
* an executor ref key.
|
|
8
|
+
*/
|
|
9
|
+
/** The kind of side‑effects a tool has. */
|
|
10
|
+
type ToolKind = "ReadOnly" | "WritesFiles" | "ExecutesCode" | "Network";
|
|
11
|
+
/** 4‑level safety classification (mirrors Claude Code / CodeWhale). */
|
|
12
|
+
type CommandSafety = "Safe" | "WorkspaceSafe" | "RequiresApproval" | "Dangerous";
|
|
13
|
+
/** Identifies which plugin (or "core") owns this tool. */
|
|
14
|
+
type ToolOwnerRef = string;
|
|
15
|
+
/** Routing key — resolved by the registry to find the handler. */
|
|
16
|
+
type ToolExecutorRef = string;
|
|
17
|
+
/**
|
|
18
|
+
* Static description of a tool — its name, schema, safety level, and
|
|
19
|
+
* when it should be visible.
|
|
20
|
+
*
|
|
21
|
+
* Registered once at startup and stays immutable for the session lifetime.
|
|
22
|
+
*/
|
|
23
|
+
interface ToolDescriptor {
|
|
24
|
+
/** Unique tool name, e.g. "bash" or "read_file". */
|
|
25
|
+
name: string;
|
|
26
|
+
/** Human‑readable description injected into the LLM system prompt. */
|
|
27
|
+
description: string;
|
|
28
|
+
/** JSON Schema for the tool's input parameters. */
|
|
29
|
+
inputSchema: Record<string, unknown>;
|
|
30
|
+
/** Side‑effect category. */
|
|
31
|
+
kind: ToolKind;
|
|
32
|
+
/** Baseline safety level. */
|
|
33
|
+
safety: CommandSafety;
|
|
34
|
+
/** When this tool is visible — evaluated each turn. */
|
|
35
|
+
availability: AvailabilityExpr;
|
|
36
|
+
/** Key to look up the handler in the registry. */
|
|
37
|
+
executor: ToolExecutorRef;
|
|
38
|
+
/** "core" or the plugin id that registered this tool. */
|
|
39
|
+
owner: ToolOwnerRef;
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* Expression tree for tool availability.
|
|
43
|
+
*
|
|
44
|
+
* Evaluated at the start of every turn to determine which tools
|
|
45
|
+
* are visible in the LLM tool catalog.
|
|
46
|
+
*/
|
|
47
|
+
type AvailabilityExpr = {
|
|
48
|
+
type: "always";
|
|
49
|
+
} | {
|
|
50
|
+
type: "never";
|
|
51
|
+
reason: string;
|
|
52
|
+
} | {
|
|
53
|
+
type: "env";
|
|
54
|
+
key: string;
|
|
55
|
+
equals: string;
|
|
56
|
+
} | {
|
|
57
|
+
type: "setting";
|
|
58
|
+
path: string;
|
|
59
|
+
equals: unknown;
|
|
60
|
+
} | {
|
|
61
|
+
type: "flag";
|
|
62
|
+
flag: string;
|
|
63
|
+
} | {
|
|
64
|
+
type: "platform";
|
|
65
|
+
platform: "windows" | "linux";
|
|
66
|
+
} | {
|
|
67
|
+
type: "mcp_connected";
|
|
68
|
+
serverName: string;
|
|
69
|
+
} | {
|
|
70
|
+
type: "has_plugin";
|
|
71
|
+
pluginId: string;
|
|
72
|
+
} | {
|
|
73
|
+
type: "session_mode";
|
|
74
|
+
mode: string;
|
|
75
|
+
} | {
|
|
76
|
+
type: "all";
|
|
77
|
+
exprs: AvailabilityExpr[];
|
|
78
|
+
} | {
|
|
79
|
+
type: "any";
|
|
80
|
+
exprs: AvailabilityExpr[];
|
|
81
|
+
} | {
|
|
82
|
+
type: "not";
|
|
83
|
+
expr: AvailabilityExpr;
|
|
84
|
+
};
|
|
85
|
+
/** Result of the tool planner — which tools go to the LLM. */
|
|
86
|
+
interface ToolPlan {
|
|
87
|
+
/** Tools that will appear in the LLM catalog. */
|
|
88
|
+
visible: ToolDescriptor[];
|
|
89
|
+
/** Tools that are hidden (unavailable), each with a reason. */
|
|
90
|
+
hidden: HiddenTool[];
|
|
91
|
+
}
|
|
92
|
+
/** A tool that was hidden with the reason why. */
|
|
93
|
+
interface HiddenTool {
|
|
94
|
+
tool: ToolDescriptor;
|
|
95
|
+
reason: string;
|
|
96
|
+
}
|
|
97
|
+
/** A single tool invocation created by the LLM. */
|
|
98
|
+
interface ToolInvocation {
|
|
99
|
+
/** Unique call id from the provider's tool_use block. */
|
|
100
|
+
callId: string;
|
|
101
|
+
/** Tool name as registered. */
|
|
102
|
+
toolName: string;
|
|
103
|
+
/** Parsed tool input (provider‑side consolidation). */
|
|
104
|
+
payload: Record<string, unknown>;
|
|
105
|
+
}
|
|
106
|
+
/** The handler that actually executes a tool. */
|
|
107
|
+
interface ToolHandler {
|
|
108
|
+
/**
|
|
109
|
+
* Execute the tool.
|
|
110
|
+
*
|
|
111
|
+
* Each handler receives an AbortSignal — when the user hits Ctrl+C,
|
|
112
|
+
* the signal fires and the handler should stop as soon as possible.
|
|
113
|
+
*/
|
|
114
|
+
handle(invocation: ToolInvocation, signal: AbortSignal): Promise<ToolResult>;
|
|
115
|
+
}
|
|
116
|
+
/** Result of a completed tool execution. */
|
|
117
|
+
interface ToolResult {
|
|
118
|
+
/** Whether execution succeeded (false = error). */
|
|
119
|
+
success: boolean;
|
|
120
|
+
/** Human‑readable output text. */
|
|
121
|
+
content: string;
|
|
122
|
+
/** Optional metadata for the rendering layer. */
|
|
123
|
+
metadata?: {
|
|
124
|
+
/** Wall‑clock duration in milliseconds. */durationMs: number; /** Whether the output was truncated. */
|
|
125
|
+
truncated?: boolean; /** Where the truncation occurred (character index). */
|
|
126
|
+
truncatedAt?: number;
|
|
127
|
+
};
|
|
128
|
+
}
|
|
129
|
+
//#endregion
|
|
130
|
+
//#region src/availability.d.ts
|
|
131
|
+
/**
|
|
132
|
+
* Snapshot of the runtime environment passed to the availability evaluator.
|
|
133
|
+
* Updated each turn before `buildToolPlan()` runs.
|
|
134
|
+
*/
|
|
135
|
+
interface EvalContext {
|
|
136
|
+
/** Current platform ("windows" | "linux"). */
|
|
137
|
+
platform: "windows" | "linux";
|
|
138
|
+
/** Current permission mode (from the session). */
|
|
139
|
+
sessionMode: string;
|
|
140
|
+
/** Enabled feature flags. */
|
|
141
|
+
flags: Set<string>;
|
|
142
|
+
/** Settings/configuration values keyed by dot‑path. */
|
|
143
|
+
settings: Record<string, unknown>;
|
|
144
|
+
/** Environment variable overrides. */
|
|
145
|
+
env: Record<string, string>;
|
|
146
|
+
/** Connected MCP server names. */
|
|
147
|
+
connectedMcpServers: Set<string>;
|
|
148
|
+
/** Loaded plugin ids. */
|
|
149
|
+
loadedPlugins: Set<string>;
|
|
150
|
+
}
|
|
151
|
+
/**
|
|
152
|
+
* Evaluate an availability expression against the current context.
|
|
153
|
+
*
|
|
154
|
+
* Returns `{ available: true }` or `{ available: false, reason: string }`.
|
|
155
|
+
*
|
|
156
|
+
* ```ts
|
|
157
|
+
* const result = evaluateAvailability(expr, ctx);
|
|
158
|
+
* if (!result.available) {
|
|
159
|
+
* console.log(`Tool hidden because: ${result.reason}`);
|
|
160
|
+
* }
|
|
161
|
+
* ```
|
|
162
|
+
*/
|
|
163
|
+
declare function evaluateAvailability(expr: AvailabilityExpr, ctx: EvalContext): {
|
|
164
|
+
available: boolean;
|
|
165
|
+
reason?: string;
|
|
166
|
+
};
|
|
167
|
+
//#endregion
|
|
168
|
+
//#region src/registry.d.ts
|
|
169
|
+
/**
|
|
170
|
+
* In‑memory registry of all registered tools and their handlers.
|
|
171
|
+
*
|
|
172
|
+
* Create one instance per process in the bootstrap phase.
|
|
173
|
+
*/
|
|
174
|
+
interface ToolRegistry {
|
|
175
|
+
/** Register a tool descriptor and its handler. */
|
|
176
|
+
register(descriptor: ToolDescriptor, handler: ToolHandler): void;
|
|
177
|
+
/** Look up a descriptor by name. Returns undefined if not found. */
|
|
178
|
+
resolve(name: string): ToolDescriptor | undefined;
|
|
179
|
+
/** Look up a handler by executor key. Throws if not registered. */
|
|
180
|
+
resolveExecutor(descriptor: ToolDescriptor): ToolHandler;
|
|
181
|
+
/** Return every registered descriptor. */
|
|
182
|
+
listAll(): ToolDescriptor[];
|
|
183
|
+
/** Return the total number of registered tools. */
|
|
184
|
+
count(): number;
|
|
185
|
+
}
|
|
186
|
+
/**
|
|
187
|
+
* Create a new empty ToolRegistry.
|
|
188
|
+
*/
|
|
189
|
+
declare function createToolRegistry(): ToolRegistry;
|
|
190
|
+
//#endregion
|
|
191
|
+
//#region src/builtin/files/read-file.d.ts
|
|
192
|
+
declare const descriptor$3: ToolDescriptor;
|
|
193
|
+
declare const handler: ToolHandler;
|
|
194
|
+
//#endregion
|
|
195
|
+
//#region src/builtin/agent/task.d.ts
|
|
196
|
+
/**
|
|
197
|
+
* TaskManager 的最小接口 — lynx-tools 不依赖 lynx-agent,
|
|
198
|
+
* 实际实例在 bootstrap 时注入。
|
|
199
|
+
*/
|
|
200
|
+
interface TaskManagerOps {
|
|
201
|
+
start(id: string, label: string, run: (signal: AbortSignal) => Promise<void>): Promise<void>;
|
|
202
|
+
stop(id: string): Promise<void>;
|
|
203
|
+
get(id: string): {
|
|
204
|
+
id: string;
|
|
205
|
+
label: string;
|
|
206
|
+
status: string;
|
|
207
|
+
startedAt: number;
|
|
208
|
+
stoppedAt?: number;
|
|
209
|
+
error?: string;
|
|
210
|
+
output?: string;
|
|
211
|
+
progress?: number;
|
|
212
|
+
} | undefined;
|
|
213
|
+
list(): Array<{
|
|
214
|
+
id: string;
|
|
215
|
+
label: string;
|
|
216
|
+
status: string;
|
|
217
|
+
}>;
|
|
218
|
+
getOutput(id: string): string;
|
|
219
|
+
update(id: string, patch: {
|
|
220
|
+
label?: string;
|
|
221
|
+
status?: string;
|
|
222
|
+
}): void;
|
|
223
|
+
}
|
|
224
|
+
/**
|
|
225
|
+
* Inject the real TaskManager backend.
|
|
226
|
+
*
|
|
227
|
+
* Called during bootstrap after the engine is created.
|
|
228
|
+
* Before injection, the handler returns mock results for test compatibility.
|
|
229
|
+
*/
|
|
230
|
+
declare function injectTaskManager(tm: TaskManagerOps): void;
|
|
231
|
+
/**
|
|
232
|
+
* Create a task handler bound to a specific {@link TaskManagerOps}.
|
|
233
|
+
*
|
|
234
|
+
* Factory alternative to {@link injectTaskManager} — useful when the
|
|
235
|
+
* handler needs to be registered independently of the module‑level singleton.
|
|
236
|
+
*/
|
|
237
|
+
declare function createTaskHandler(tm: TaskManagerOps): ToolHandler;
|
|
238
|
+
//#endregion
|
|
239
|
+
//#region ../lynx-agent/src/memory/manager.d.ts
|
|
240
|
+
/**
|
|
241
|
+
* Memory manager — persistent key‑value facts that survive
|
|
242
|
+
* across sessions.
|
|
243
|
+
*
|
|
244
|
+
* Memory entries are simple markdown files with frontmatter,
|
|
245
|
+
* stored in a configured directory. The agent can read/write
|
|
246
|
+
* memories via tools.
|
|
247
|
+
*
|
|
248
|
+
* Pattern: inspired by Claude Code's memory system —
|
|
249
|
+
* ● Each fact is one file
|
|
250
|
+
* ● Frontmatter contains metadata (type, tags, timestamp)
|
|
251
|
+
* ● An index file (MEMORY.md) lists all entries for fast scanning
|
|
252
|
+
* ● Loading reads the index first, then lazy‑loads individual files
|
|
253
|
+
*/
|
|
254
|
+
interface MemoryEntry {
|
|
255
|
+
/** File stem (slug). */
|
|
256
|
+
name: string;
|
|
257
|
+
/** Short description for relevance matching. */
|
|
258
|
+
description: string;
|
|
259
|
+
/** When the entry was last modified (Unix ms). */
|
|
260
|
+
updatedAt: number;
|
|
261
|
+
/** Full markdown content (lazy‑loaded). */
|
|
262
|
+
content?: string;
|
|
263
|
+
/** Metadata from frontmatter. */
|
|
264
|
+
type: "user" | "feedback" | "project" | "reference";
|
|
265
|
+
/** Absolute file path on disk. */
|
|
266
|
+
filePath: string;
|
|
267
|
+
/** Arbitrary extra metadata fields from frontmatter (e.g. tags, source). */
|
|
268
|
+
metadata?: Record<string, unknown>;
|
|
269
|
+
}
|
|
270
|
+
interface MemoryManager {
|
|
271
|
+
/** Load the index (all memory names + descriptions). */
|
|
272
|
+
list(): MemoryEntry[];
|
|
273
|
+
/** Load a single memory entry by name. */
|
|
274
|
+
get(name: string): MemoryEntry | undefined;
|
|
275
|
+
/** Write (create or update) a memory entry. */
|
|
276
|
+
put(entry: MemoryEntry): void;
|
|
277
|
+
/** Delete a memory entry by name. */
|
|
278
|
+
delete(name: string): boolean;
|
|
279
|
+
/** Reload the index from disk. */
|
|
280
|
+
reload(): void;
|
|
281
|
+
/** 全文搜索记忆 — 在名称、描述、内容中匹配关键词。按相关度排序。 */
|
|
282
|
+
search(query: string): MemoryEntry[];
|
|
283
|
+
/** 去重压缩 — 合并 Jaccard 相似度 > 0.8 的条目。返回合并后的条目列表。 */
|
|
284
|
+
compact(): MemoryEntry[];
|
|
285
|
+
/** 按 glob 模式批量删除匹配的记忆。返回删除的条目数。 */
|
|
286
|
+
forget(pattern: string): number;
|
|
287
|
+
/** 将所有记忆序列化为 JSON 字符串。 */
|
|
288
|
+
exportAll(): string;
|
|
289
|
+
/** 从 JSON 字符串批量导入记忆。跳过已存在的同名条目。返回导入数量。 */
|
|
290
|
+
importAll(data: string): number;
|
|
291
|
+
/** 合并另一个 memory 目录中的记忆文件。跳过冲突。返回合并的条目数。 */
|
|
292
|
+
merge(sourceDir: string): number;
|
|
293
|
+
}
|
|
294
|
+
//#endregion
|
|
295
|
+
//#region src/builtin/memory/memory-write.d.ts
|
|
296
|
+
declare const descriptor$1: ToolDescriptor;
|
|
297
|
+
/**
|
|
298
|
+
* 创建绑定到指定 {@link MemoryManager} 的 memory_write 处理器。
|
|
299
|
+
*
|
|
300
|
+
* 工厂模式 — 管理器在启动时注入,使工具写入真实的 memory 目录。
|
|
301
|
+
*/
|
|
302
|
+
declare function createMemoryWriteHandler(memoryManager: MemoryManager): ToolHandler;
|
|
303
|
+
//#endregion
|
|
304
|
+
//#region src/builtin/mcp/mcp-auth.d.ts
|
|
305
|
+
/** McpManager 的最小接口 — lynx-tools 不依赖 lynx-agent。 */
|
|
306
|
+
interface McpAuthOps {
|
|
307
|
+
reconnect(serverName: string): Promise<{
|
|
308
|
+
status: string;
|
|
309
|
+
}>;
|
|
310
|
+
}
|
|
311
|
+
/** 工具描述符 — 注册到 ToolRegistry 的静态元数据。 */
|
|
312
|
+
declare const descriptor: ToolDescriptor;
|
|
313
|
+
/**
|
|
314
|
+
* 创建 McpAuthTool 的 handler,绑定到给定的 McpAuthOps。
|
|
315
|
+
*
|
|
316
|
+
* 工厂模式 — 实际 McpManager 在 bootstrap 时注入。
|
|
317
|
+
*/
|
|
318
|
+
declare function createMcpAuthHandler(mcpOps: McpAuthOps): ToolHandler;
|
|
319
|
+
//#endregion
|
|
320
|
+
//#region src/builtin/interact/send-message.d.ts
|
|
321
|
+
/** 消息发送器接口 —— 由调用方注入具体实现。 */
|
|
322
|
+
interface MessageSender {
|
|
323
|
+
/**
|
|
324
|
+
* 通过指定通道发送消息。
|
|
325
|
+
* @param channel 通道标识(如 "feishu")
|
|
326
|
+
* @param content 消息内容
|
|
327
|
+
* @param recipients 可选接收人列表
|
|
328
|
+
* @returns 包含 messageId 的结果
|
|
329
|
+
*/
|
|
330
|
+
send(channel: string, content: string, recipients?: string[]): Promise<{
|
|
331
|
+
messageId: string;
|
|
332
|
+
}>;
|
|
333
|
+
}
|
|
334
|
+
declare const descriptor$2: ToolDescriptor;
|
|
335
|
+
/**
|
|
336
|
+
* 创建 SendMessageTool 的处理器。
|
|
337
|
+
*
|
|
338
|
+
* 通过工厂注入 MessageSender 实现,避免直接 import lynx-channels。
|
|
339
|
+
* 在 bootstrap 阶段将真实的通道发送器注入此处。
|
|
340
|
+
*/
|
|
341
|
+
declare function createSendMessageHandler(sender: MessageSender): ToolHandler;
|
|
342
|
+
//#endregion
|
|
343
|
+
//#region src/builtin/index.d.ts
|
|
344
|
+
/** All built‑in (descriptor, handler) pairs in registration order. */
|
|
345
|
+
declare const BUILTIN_TOOLS: Array<{
|
|
346
|
+
descriptor: typeof descriptor$3;
|
|
347
|
+
handler: typeof handler;
|
|
348
|
+
}>;
|
|
349
|
+
/**
|
|
350
|
+
* Register all built‑in tool (descriptor, handler) pairs with the given registry.
|
|
351
|
+
*
|
|
352
|
+
* Each pair is registered atomically — if one fails (duplicate name), the error
|
|
353
|
+
* propagates so the caller can decide whether to abort or skip.
|
|
354
|
+
*/
|
|
355
|
+
declare function registerBuiltinTools(registry: ToolRegistry): void;
|
|
356
|
+
/** Return the list of built‑in descriptors (without registering). */
|
|
357
|
+
declare function listBuiltinDescriptors(): (typeof BUILTIN_TOOLS)[number]["descriptor"][];
|
|
358
|
+
//#endregion
|
|
359
|
+
//#region src/planner.d.ts
|
|
360
|
+
/**
|
|
361
|
+
* Compute the tool plan for the current turn.
|
|
362
|
+
*
|
|
363
|
+
* Every registered tool is evaluated against the availability context.
|
|
364
|
+
* Visible tools go into the LLM catalog; hidden tools are returned with
|
|
365
|
+
* a reason so the debug/log layer can report them.
|
|
366
|
+
*
|
|
367
|
+
* ```ts
|
|
368
|
+
* const plan = buildToolPlan(registry, evalCtx);
|
|
369
|
+
* console.log(`${plan.visible.length} visible, ${plan.hidden.length} hidden`);
|
|
370
|
+
* ```
|
|
371
|
+
*/
|
|
372
|
+
declare function buildToolPlan(registry: ToolRegistry, ctx: EvalContext): ToolPlan;
|
|
373
|
+
//#endregion
|
|
374
|
+
//#region src/safety.d.ts
|
|
375
|
+
/**
|
|
376
|
+
* Escalate the safety level if the command touches a sensitive path.
|
|
377
|
+
*
|
|
378
|
+
* Uses the 4‑level sensitivity classification from {@link classifySensitivity}.
|
|
379
|
+
* Even a "Safe" tool becomes Dangerous if it tries to read ~/.ssh.
|
|
380
|
+
*/
|
|
381
|
+
declare function escalateForSensitivePaths(safety: CommandSafety, paths: string[]): CommandSafety;
|
|
382
|
+
/**
|
|
383
|
+
* Returns true if the tool requires interactive user confirmation.
|
|
384
|
+
*/
|
|
385
|
+
declare function needsApproval(safety: CommandSafety): boolean;
|
|
386
|
+
/**
|
|
387
|
+
* Returns true if the tool can run automatically in yolo/headless mode.
|
|
388
|
+
*/
|
|
389
|
+
declare function isHeadlessSafe(safety: CommandSafety): boolean;
|
|
390
|
+
/** Human‑readable labels for each safety level. */
|
|
391
|
+
declare const SAFETY_LABELS: Record<CommandSafety, string>;
|
|
392
|
+
//#endregion
|
|
393
|
+
//#region src/safety/sanitize.d.ts
|
|
394
|
+
/**
|
|
395
|
+
* Unicode sanitization — remove invisible and control characters
|
|
396
|
+
* that could be used for prompt injection attacks.
|
|
397
|
+
*
|
|
398
|
+
* All patterns use new RegExp() with \\uXXXX string escapes
|
|
399
|
+
* to avoid filesystem encoding of literal Unicode characters.
|
|
400
|
+
*
|
|
401
|
+
* References:
|
|
402
|
+
* - Unicode Technical Report #36 (Security Considerations)
|
|
403
|
+
* - CWE-838: Inappropriate Encoding for Output Context
|
|
404
|
+
*/
|
|
405
|
+
/**
|
|
406
|
+
* Strip invisible and potentially dangerous Unicode characters from text.
|
|
407
|
+
*
|
|
408
|
+
* Preserves CJK Unified ideographs, emoji, combining diacritical marks,
|
|
409
|
+
* and other legitimate Unicode.
|
|
410
|
+
*/
|
|
411
|
+
declare function sanitizeUnicode(input: string): string;
|
|
412
|
+
//#endregion
|
|
413
|
+
//#region src/safety/path-check.d.ts
|
|
414
|
+
/**
|
|
415
|
+
* Path traversal / jailbreak detection.
|
|
416
|
+
*
|
|
417
|
+
* Verifies that a resolved file path stays within the workspace root.
|
|
418
|
+
* Also catches null-byte injection attacks that can truncate paths
|
|
419
|
+
* in C‑based filesystem APIs.
|
|
420
|
+
*/
|
|
421
|
+
/**
|
|
422
|
+
* Check whether a file path is safely contained within the workspace root.
|
|
423
|
+
*
|
|
424
|
+
* Algorithm:
|
|
425
|
+
* 1. Reject paths containing null bytes (truncation attack).
|
|
426
|
+
* 2. Resolve to absolute path, eliminating `../` segments.
|
|
427
|
+
* 3. Resolve symlinks to their real physical location.
|
|
428
|
+
* 4. Verify the final path starts with the workspace root.
|
|
429
|
+
*
|
|
430
|
+
* @returns true if the path is safely inside the workspace.
|
|
431
|
+
*/
|
|
432
|
+
declare function isPathSafe(filePath: string, workspaceRoot: string): boolean;
|
|
433
|
+
//#endregion
|
|
434
|
+
//#region src/safety/trusted-cmd.d.ts
|
|
435
|
+
/**
|
|
436
|
+
* Trusted command whitelist — commands that are safe to execute
|
|
437
|
+
* without interactive user confirmation.
|
|
438
|
+
*
|
|
439
|
+
* These are read‑only or read‑heavy commands that don't modify
|
|
440
|
+
* the filesystem or network. Even in `--yolo` mode, commands
|
|
441
|
+
* not on this list still go through safety escalation.
|
|
442
|
+
*/
|
|
443
|
+
/**
|
|
444
|
+
* Check if a command is on the trusted whitelist.
|
|
445
|
+
*
|
|
446
|
+
* For commands with sub‑command gating (git, npm, pnpm),
|
|
447
|
+
* the first argument is checked against allowed sub‑commands.
|
|
448
|
+
*/
|
|
449
|
+
declare function isTrustedCommand(command: string, args?: string[]): boolean;
|
|
450
|
+
//#endregion
|
|
451
|
+
//#region src/safety/blocked-cmd.d.ts
|
|
452
|
+
/**
|
|
453
|
+
* Blocked command blacklist — commands that are ALWAYS rejected
|
|
454
|
+
* regardless of permission mode (including `--yolo`).
|
|
455
|
+
*
|
|
456
|
+
* These patterns match destructive or privilege‑escalation operations
|
|
457
|
+
* that should never run through an AI agent.
|
|
458
|
+
*/
|
|
459
|
+
/**
|
|
460
|
+
* Check if a command string matches any blocked pattern.
|
|
461
|
+
*
|
|
462
|
+
* @returns The block reason if blocked, or null if safe.
|
|
463
|
+
*/
|
|
464
|
+
declare function isBlockedCommand(command: string, args?: string[]): {
|
|
465
|
+
blocked: true;
|
|
466
|
+
reason: string;
|
|
467
|
+
} | {
|
|
468
|
+
blocked: false;
|
|
469
|
+
};
|
|
470
|
+
//#endregion
|
|
471
|
+
//#region src/safety/redact.d.ts
|
|
472
|
+
/**
|
|
473
|
+
* Secret / key redaction — detect and redact sensitive credentials
|
|
474
|
+
* from output before displaying to the user or logging.
|
|
475
|
+
*
|
|
476
|
+
* This is a defense‑in‑depth layer. The primary defense is never
|
|
477
|
+
* reading .env / secret files, but if a secret leaks into output
|
|
478
|
+
* (e.g. from a tool result or LLM response), we redact it here.
|
|
479
|
+
*/
|
|
480
|
+
/**
|
|
481
|
+
* Redact all detected secrets from the given text.
|
|
482
|
+
*
|
|
483
|
+
* @returns The text with secrets replaced by `[REDACTED]` or `sk-...XyZ1`.
|
|
484
|
+
*/
|
|
485
|
+
declare function redactSecrets(text: string): string;
|
|
486
|
+
//#endregion
|
|
487
|
+
//#region src/safety/sensitive.d.ts
|
|
488
|
+
/**
|
|
489
|
+
* Sensitive file classification — 4‑level protection system.
|
|
490
|
+
*
|
|
491
|
+
* Levels (increasing severity):
|
|
492
|
+
* Low — normal files, write allowed
|
|
493
|
+
* Medium — config/build files, write prompts confirmation
|
|
494
|
+
* High — env/secret files, read‑only (write blocked)
|
|
495
|
+
* Critical — SSH/GPG keys, never read or write
|
|
496
|
+
*
|
|
497
|
+
* This replaces the flat `SENSITIVE_PATHS` Set in safety.ts
|
|
498
|
+
* with a tiered system that enables fine‑grained access control.
|
|
499
|
+
*/
|
|
500
|
+
type SensitivityLevel = "Low" | "Medium" | "High" | "Critical";
|
|
501
|
+
/**
|
|
502
|
+
* Classify a file path by sensitivity level.
|
|
503
|
+
*
|
|
504
|
+
* The path is tested against all rules in order. The first match wins.
|
|
505
|
+
* Negation patterns (`!`) remove previous matches at the same level.
|
|
506
|
+
*
|
|
507
|
+
* @returns The sensitivity level for the given path.
|
|
508
|
+
*/
|
|
509
|
+
declare function classifySensitivity(filePath: string): SensitivityLevel;
|
|
510
|
+
//#endregion
|
|
511
|
+
//#region src/safety/index.d.ts
|
|
512
|
+
/** A single blocked command pattern (for external display / config). */
|
|
513
|
+
interface BlockedPattern {
|
|
514
|
+
reason: string;
|
|
515
|
+
pattern: string;
|
|
516
|
+
}
|
|
517
|
+
//#endregion
|
|
518
|
+
export { type AvailabilityExpr, type BlockedPattern, type CommandSafety, type EvalContext, type HiddenTool, SAFETY_LABELS, type SensitivityLevel, type ToolDescriptor, type ToolExecutorRef, type ToolHandler, type ToolInvocation, type ToolKind, type ToolOwnerRef, type ToolPlan, type ToolRegistry, type ToolResult, buildToolPlan, classifySensitivity as classifyPath, createMcpAuthHandler, createMemoryWriteHandler, createSendMessageHandler, createTaskHandler, createToolRegistry, escalateForSensitivePaths, evaluateAvailability, injectTaskManager, isBlockedCommand, isHeadlessSafe, isTrustedCommand, isPathSafe as isWithinWorkspace, listBuiltinDescriptors, descriptor as mcpAuthDescriptor, descriptor$1 as memoryWriteDescriptor, needsApproval, redactSecrets, registerBuiltinTools, sanitizeUnicode, descriptor$2 as sendMessageDescriptor };
|
|
519
|
+
//# sourceMappingURL=index.d.mts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/availability.ts","../src/registry.ts","../src/builtin/files/read-file.ts","../src/builtin/agent/task.ts","../../lynx-agent/src/memory/manager.ts","../src/builtin/memory/memory-write.ts","../src/builtin/mcp/mcp-auth.ts","../src/builtin/interact/send-message.ts","../src/builtin/index.ts","../src/planner.ts","../src/safety.ts","../src/safety/sanitize.ts","../src/safety/path-check.ts","../src/safety/trusted-cmd.ts","../src/safety/blocked-cmd.ts","../src/safety/redact.ts","../src/safety/sensitive.ts","../src/safety/index.ts"],"mappings":"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"}
|