@octopi-agent/engine 0.90.11 → 0.98.4
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/config-admin/agent-presets.d.ts +70 -0
- package/dist/config-admin/agent-presets.js +243 -0
- package/dist/config-admin/discover.d.ts +30 -0
- package/dist/config-admin/discover.js +48 -0
- package/dist/config-admin/env.d.ts +22 -0
- package/dist/config-admin/env.js +41 -0
- package/dist/config-admin/index.d.ts +20 -0
- package/dist/config-admin/index.js +15 -0
- package/dist/config-admin/model-presets.d.ts +75 -0
- package/dist/config-admin/model-presets.js +249 -0
- package/dist/config-admin/name-guard.d.ts +14 -0
- package/dist/config-admin/name-guard.js +24 -0
- package/dist/config-admin/patch.d.ts +56 -0
- package/dist/config-admin/patch.js +201 -0
- package/dist/config-admin/port.d.ts +68 -0
- package/dist/config-admin/port.js +21 -0
- package/dist/config-admin/redact.d.ts +39 -0
- package/dist/config-admin/redact.js +42 -0
- package/dist/config-schema/agent.d.ts +45 -1
- package/dist/config-schema/context.d.ts +6 -1
- package/dist/config-schema/context.js +8 -0
- package/dist/config-schema/engine.d.ts +110 -4
- package/dist/config-schema/governance.d.ts +45 -1
- package/dist/config-schema/governance.js +187 -0
- package/dist/config-schema/models.d.ts +5 -2
- package/dist/config-schema/models.js +4 -1
- package/dist/config-schema/observability.d.ts +9 -0
- package/dist/config-schema/observability.js +29 -0
- package/dist/config-schema/run.d.ts +3 -0
- package/dist/config-schema/run.js +14 -0
- package/dist/config.d.ts +29 -4
- package/dist/config.js +15 -4
- package/dist/harness/activation/dispatcher.d.ts +8 -2
- package/dist/harness/activation/dispatcher.js +33 -5
- package/dist/harness/activation/inbox.d.ts +87 -0
- package/dist/harness/activation/inbox.js +169 -0
- package/dist/harness/activation/runtime.d.ts +9 -8
- package/dist/harness/activation/runtime.js +100 -8
- package/dist/harness/activation/types.d.ts +19 -0
- package/dist/harness/activation/types.js +2 -0
- package/dist/harness/agent/builder.d.ts +26 -1
- package/dist/harness/agent/builder.js +85 -37
- package/dist/harness/agent/config-bridge.d.ts +5 -0
- package/dist/harness/agent/config-bridge.js +3 -0
- package/dist/harness/agent/config-integrity.d.ts +138 -0
- package/dist/harness/agent/config-integrity.js +235 -0
- package/dist/harness/agent/wire-agent-builder.js +7 -1
- package/dist/harness/collaboration/autonomous-subsystem/index.d.ts +2 -2
- package/dist/harness/collaboration/autonomous-subsystem/index.js +1 -1
- package/dist/harness/collaboration/autonomous-subsystem/loader.js +3 -0
- package/dist/harness/collaboration/autonomous-subsystem/sense/engine.js +19 -2
- package/dist/harness/collaboration/autonomous-subsystem/think/completion-guard.d.ts +40 -0
- package/dist/harness/collaboration/autonomous-subsystem/think/completion-guard.js +59 -0
- package/dist/harness/collaboration/autonomous-subsystem/think/executor.js +3 -1
- package/dist/harness/collaboration/autonomous-subsystem/think/index.d.ts +2 -0
- package/dist/harness/collaboration/autonomous-subsystem/think/index.js +1 -0
- package/dist/harness/collaboration/autonomous-subsystem/think/model-resolver.js +1 -1
- package/dist/harness/collaboration/autonomous-subsystem/types.d.ts +9 -0
- package/dist/harness/collaboration/delegation/child-run.js +21 -5
- package/dist/harness/collaboration/delegation/notifier.js +4 -3
- package/dist/harness/collaboration/delegation/service.js +2 -3
- package/dist/harness/collaboration/delegation/wiring.js +6 -5
- package/dist/harness/collaboration/orchestration/reflector/llm-reflector.d.ts +1 -1
- package/dist/harness/collaboration/orchestration/reflector/llm-reflector.js +1 -1
- package/dist/harness/context/capabilities/compact/engine.d.ts +30 -0
- package/dist/harness/context/capabilities/compact/engine.js +198 -46
- package/dist/harness/context/capabilities/compact/handover.d.ts +78 -0
- package/dist/harness/context/capabilities/compact/handover.js +107 -0
- package/dist/harness/context/capabilities/compact/index.d.ts +3 -1
- package/dist/harness/context/capabilities/compact/index.js +2 -1
- package/dist/harness/context/capabilities/compact/types.d.ts +30 -1
- package/dist/harness/context/capabilities/summary/executor.js +2 -1
- package/dist/harness/context/capabilities/summary/policies.js +8 -5
- package/dist/harness/context/capabilities/summary/resolver.d.ts +1 -1
- package/dist/harness/context/capabilities/summary/resolver.js +4 -4
- package/dist/harness/context/capabilities/summary/types.d.ts +2 -2
- package/dist/harness/context/constitution/default-agents.md +11 -10
- package/dist/harness/context/default-context-engine.d.ts +34 -4
- package/dist/harness/context/default-context-engine.js +194 -49
- package/dist/harness/context/hybrid-compressor.js +6 -0
- package/dist/harness/context/layers.d.ts +2 -4
- package/dist/harness/context/layers.js +9 -11
- package/dist/harness/context/llm-summarizer.d.ts +2 -8
- package/dist/harness/context/llm-summarizer.js +69 -91
- package/dist/harness/context/message-selector.js +4 -3
- package/dist/harness/context/summarize.d.ts +3 -1
- package/dist/harness/context/summarize.js +9 -4
- package/dist/harness/context/system-prompt-assembler.d.ts +2 -0
- package/dist/harness/context/system-prompt-assembler.js +1 -0
- package/dist/harness/context/truncate-compressor.js +7 -0
- package/dist/harness/context/turn-envelope.d.ts +3 -2
- package/dist/harness/context/turn-envelope.js +3 -2
- package/dist/harness/context/types.d.ts +33 -1
- package/dist/harness/extension/execution-environment/dangerous-commands.d.ts +28 -0
- package/dist/harness/extension/execution-environment/dangerous-commands.js +129 -0
- package/dist/harness/extension/execution-environment/effect-policy.d.ts +149 -8
- package/dist/harness/extension/execution-environment/effect-policy.js +274 -19
- package/dist/harness/extension/execution-environment/index.d.ts +4 -2
- package/dist/harness/extension/execution-environment/index.js +2 -1
- package/dist/harness/extension/execution-environment/kill-switch.d.ts +34 -0
- package/dist/harness/extension/execution-environment/kill-switch.js +46 -0
- package/dist/harness/extension/execution-environment/ops-audit.d.ts +204 -0
- package/dist/harness/extension/execution-environment/ops-audit.js +337 -0
- package/dist/harness/extension/execution-environment/privileged-exec.d.ts +158 -0
- package/dist/harness/extension/execution-environment/privileged-exec.js +418 -0
- package/dist/harness/extension/execution-environment/process-info.d.ts +180 -0
- package/dist/harness/extension/execution-environment/process-info.js +466 -0
- package/dist/harness/extension/execution-environment/process-isolation.d.ts +7 -0
- package/dist/harness/extension/execution-environment/process-isolation.js +9 -0
- package/dist/harness/extension/execution-environment/sandbox.d.ts +109 -0
- package/dist/harness/extension/execution-environment/sandbox.js +228 -21
- package/dist/harness/extension/execution-environment/tool-capabilities.d.ts +1 -1
- package/dist/harness/extension/execution-environment/tool-capabilities.js +6 -0
- package/dist/harness/extension/execution-environment/types.d.ts +19 -0
- package/dist/harness/extension/execution-environment/undo-log.d.ts +6 -2
- package/dist/harness/extension/execution-environment/undo-log.js +31 -10
- package/dist/harness/extension/plugin-ecosystem/channel-types.d.ts +5 -0
- package/dist/harness/extension/plugin-ecosystem/tools/allowlisted-run.js +33 -0
- package/dist/harness/extension/plugin-ecosystem/tools/ask-user.d.ts +4 -5
- package/dist/harness/extension/plugin-ecosystem/tools/ask-user.js +5 -15
- package/dist/harness/extension/plugin-ecosystem/tools/builtin.d.ts +3 -0
- package/dist/harness/extension/plugin-ecosystem/tools/builtin.js +70 -26
- package/dist/harness/extension/plugin-ecosystem/tools/document-tools.js +3 -9
- package/dist/harness/extension/plugin-ecosystem/tools/file-edit.js +3 -6
- package/dist/harness/extension/plugin-ecosystem/tools/file-ops.js +9 -5
- package/dist/harness/extension/plugin-ecosystem/tools/file-search.js +9 -130
- package/dist/harness/extension/plugin-ecosystem/tools/git-tools.js +122 -14
- package/dist/harness/extension/plugin-ecosystem/tools/index.d.ts +2 -0
- package/dist/harness/extension/plugin-ecosystem/tools/index.js +2 -0
- package/dist/harness/extension/plugin-ecosystem/tools/package-tools.js +4 -13
- package/dist/harness/extension/plugin-ecosystem/tools/platform.d.ts +25 -11
- package/dist/harness/extension/plugin-ecosystem/tools/platform.js +168 -62
- package/dist/harness/extension/plugin-ecosystem/tools/privileged-tool.d.ts +43 -0
- package/dist/harness/extension/plugin-ecosystem/tools/privileged-tool.js +350 -0
- package/dist/harness/extension/plugin-ecosystem/tools/process-tools.d.ts +30 -0
- package/dist/harness/extension/plugin-ecosystem/tools/process-tools.js +137 -0
- package/dist/harness/governance/human-in-the-loop/decision-cache.d.ts +54 -4
- package/dist/harness/governance/human-in-the-loop/decision-cache.js +42 -16
- package/dist/harness/governance/security/default-risk-policy.d.ts +1 -0
- package/dist/harness/governance/security/default-risk-policy.js +1 -0
- package/dist/harness/governance/security/default-security-guard.js +9 -0
- package/dist/harness/governance/security/index.d.ts +1 -0
- package/dist/harness/governance/security/index.js +2 -0
- package/dist/harness/governance/security/risk-evaluator.js +13 -0
- package/dist/harness/governance/security/risk-types.d.ts +12 -0
- package/dist/harness/governance/security/shell-parser-fallback.d.ts +29 -0
- package/dist/harness/governance/security/shell-parser-fallback.js +410 -0
- package/dist/harness/governance/security/shell-parser-shared.d.ts +83 -0
- package/dist/harness/governance/security/shell-parser-shared.js +188 -0
- package/dist/harness/governance/security/shell-parser-treesitter.d.ts +52 -0
- package/dist/harness/governance/security/shell-parser-treesitter.js +370 -0
- package/dist/harness/governance/security/shell-parser.d.ts +23 -10
- package/dist/harness/governance/security/shell-parser.js +37 -496
- package/dist/harness/governance/security/temp-path.d.ts +9 -0
- package/dist/harness/governance/security/temp-path.js +13 -2
- package/dist/harness/governance/security/vendor/README.md +24 -0
- package/dist/harness/governance/security/vendor/tree-sitter-bash.LICENSE.txt +21 -0
- package/dist/harness/governance/security/vendor/tree-sitter-bash.wasm +0 -0
- package/dist/harness/governance/session-acl/seed-roles.js +14 -0
- package/dist/harness/index.d.ts +2 -0
- package/dist/harness/index.js +2 -0
- package/dist/harness/knowledge/fts.js +1 -2
- package/dist/harness/knowledge/index-store.js +59 -9
- package/dist/harness/memory/index.d.ts +6 -2
- package/dist/harness/memory/index.js +4 -1
- package/dist/harness/memory/memory-events.d.ts +25 -0
- package/dist/harness/memory/memory-events.js +38 -0
- package/dist/harness/memory/sqlite/agent-db.js +15 -0
- package/dist/harness/memory/sqlite/keyword-search.d.ts +1 -0
- package/dist/harness/memory/sqlite/keyword-search.js +4 -3
- package/dist/harness/memory/sqlite/wisdom-store.d.ts +7 -2
- package/dist/harness/memory/sqlite/wisdom-store.js +51 -2
- package/dist/harness/memory/steward-policy.d.ts +3 -0
- package/dist/harness/memory/steward-policy.js +1 -1
- package/dist/harness/memory/types.d.ts +41 -3
- package/dist/harness/memory/wisdom-attribution.d.ts +136 -0
- package/dist/harness/memory/wisdom-attribution.js +287 -0
- package/dist/harness/memory/wisdom-events.d.ts +37 -0
- package/dist/harness/memory/wisdom-events.js +61 -0
- package/dist/harness/memory/wisdom-formation.d.ts +20 -1
- package/dist/harness/memory/wisdom-formation.js +55 -21
- package/dist/harness/memory/wisdom.d.ts +7 -2
- package/dist/harness/memory/wisdom.js +40 -2
- package/dist/harness/observability/observer/hub.js +8 -0
- package/dist/harness/observability/observer/run-snapshot.js +1 -0
- package/dist/harness/observability/observer/types.d.ts +4 -0
- package/dist/harness/run/agent/agent.d.ts +7 -0
- package/dist/harness/run/agent/agent.js +23 -1
- package/dist/harness/run/reliability/fallback-provider.d.ts +117 -5
- package/dist/harness/run/reliability/fallback-provider.js +262 -22
- package/dist/harness/run/reliability/harness-events.d.ts +24 -1
- package/dist/harness/run/reliability/model-error-policy.d.ts +32 -0
- package/dist/harness/run/reliability/model-error-policy.js +42 -0
- package/dist/harness/run/reliability/provider-wrapper.js +29 -2
- package/dist/harness/run/reliability/refusal-guard.d.ts +20 -0
- package/dist/harness/run/reliability/refusal-guard.js +102 -0
- package/dist/harness/run/reliability/run-agent.js +231 -33
- package/dist/harness/run/run-guard/default-run-guard.js +1 -1
- package/dist/harness/run/run-scope.d.ts +35 -0
- package/dist/harness/run/runner.d.ts +141 -2
- package/dist/harness/run/runner.js +592 -42
- package/dist/harness/session/attachments/llm-intent.js +2 -1
- package/dist/harness/session/tasks/render.d.ts +4 -1
- package/dist/harness/session/tasks/render.js +10 -7
- package/dist/harness/shared/events/agent-event-map.d.ts +66 -0
- package/dist/harness/shared/events/agent-event-map.js +5 -0
- package/dist/harness/shared/paths/glob.d.ts +52 -0
- package/dist/harness/shared/paths/glob.js +218 -0
- package/dist/harness/shared/paths/index.d.ts +84 -0
- package/dist/harness/shared/paths/index.js +179 -0
- package/dist/index.d.ts +3 -3
- package/dist/index.js +2 -2
- package/dist/integration/agent-runtime/channel-message-source.js +19 -1
- package/dist/integration/index.d.ts +2 -0
- package/dist/integration/index.js +1 -0
- package/dist/integration/observability/loop-watchdog.d.ts +56 -0
- package/dist/integration/observability/loop-watchdog.js +177 -0
- package/dist/integration/observability/metrics.d.ts +3 -0
- package/dist/integration/observability/metrics.js +18 -7
- package/dist/integration/providers/anthropic.d.ts +23 -0
- package/dist/integration/providers/anthropic.js +97 -12
- package/dist/integration/providers/fetch-timeout.d.ts +42 -0
- package/dist/integration/providers/fetch-timeout.js +51 -0
- package/dist/integration/providers/openai.d.ts +10 -0
- package/dist/integration/providers/openai.js +58 -11
- package/dist/integration/providers/provider-diagnostics.d.ts +80 -0
- package/dist/integration/providers/provider-diagnostics.js +89 -0
- package/dist/integration/providers/timeout-coherence.d.ts +52 -0
- package/dist/integration/providers/timeout-coherence.js +68 -0
- package/dist/integration/providers/wire-dump.d.ts +62 -0
- package/dist/integration/providers/wire-dump.js +111 -2
- package/dist/integration/storage/jsonl.js +4 -1
- package/dist/subsystems/cognition-steward/conceptualize/config.yaml +4 -2
- package/dist/subsystems/cognition-steward/conceptualize/handler.js +12 -20
- package/dist/subsystems/memory-steward/backfill/config.yaml +4 -2
- package/dist/subsystems/memory-steward/backfill/handler.js +44 -52
- package/dist/subsystems/wisdom-steward/attribute/SUBSYSTEM.md +24 -0
- package/dist/subsystems/wisdom-steward/attribute/config.yaml +60 -0
- package/dist/subsystems/wisdom-steward/attribute/handler.d.ts +23 -0
- package/dist/subsystems/wisdom-steward/attribute/handler.js +167 -0
- package/dist/subsystems/wisdom-steward/evaluate/handler.js +3 -1
- package/dist/subsystems/wisdom-steward/formation/config.yaml +12 -5
- package/dist/subsystems/wisdom-steward/formation/handler.js +12 -18
- package/dist/subsystems/wisdom-steward/govern/config.yaml +1 -1
- package/dist/subsystems/wisdom-steward/govern/handler.js +4 -0
- package/package.json +8 -2
|
@@ -44,7 +44,8 @@ export function createLlmIntentResolver(provider, opts) {
|
|
|
44
44
|
{ role: 'system', content: INTENT_SYSTEM },
|
|
45
45
|
{ role: 'user', content: lines.join('\n') },
|
|
46
46
|
],
|
|
47
|
-
|
|
47
|
+
// 未显式配置即不发送:由模型配置(ModelInfo.temperature)或服务端默认决定
|
|
48
|
+
temperature: opts?.temperature,
|
|
48
49
|
maxTokens: opts?.maxTokens ?? 300,
|
|
49
50
|
});
|
|
50
51
|
const raw = (response.content ?? '').trim();
|
|
@@ -7,9 +7,12 @@ import type { SessionTask } from './types.js';
|
|
|
7
7
|
* 仅包含未闭合 goal;step 只出现 rollup,不罗列全部描述。
|
|
8
8
|
*
|
|
9
9
|
* @param tasks - 会话全部任务(含 step)
|
|
10
|
+
* @param opts - includeGuidance=false 时省略末尾「说明」段(交接式摘要等非对话消费者用)
|
|
10
11
|
* @returns 注入字符串;无活跃 goal 时返回空串
|
|
11
12
|
*/
|
|
12
|
-
export declare function renderSessionTasksInjection(tasks: SessionTask[]
|
|
13
|
+
export declare function renderSessionTasksInjection(tasks: SessionTask[], opts?: {
|
|
14
|
+
includeGuidance?: boolean;
|
|
15
|
+
}): string;
|
|
13
16
|
/**
|
|
14
17
|
* 从会话任务提取检索主题线索(Memory/Cognition 层 query 用)。
|
|
15
18
|
*
|
|
@@ -23,9 +23,10 @@ function stepProgressLine(goalId, all) {
|
|
|
23
23
|
* 仅包含未闭合 goal;step 只出现 rollup,不罗列全部描述。
|
|
24
24
|
*
|
|
25
25
|
* @param tasks - 会话全部任务(含 step)
|
|
26
|
+
* @param opts - includeGuidance=false 时省略末尾「说明」段(交接式摘要等非对话消费者用)
|
|
26
27
|
* @returns 注入字符串;无活跃 goal 时返回空串
|
|
27
28
|
*/
|
|
28
|
-
export function renderSessionTasksInjection(tasks) {
|
|
29
|
+
export function renderSessionTasksInjection(tasks, opts) {
|
|
29
30
|
const goals = tasks
|
|
30
31
|
.filter((t) => !t.parentId && isActive(t.status))
|
|
31
32
|
.sort((a, b) => a.createdAt - b.createdAt);
|
|
@@ -46,12 +47,14 @@ export function renderSessionTasksInjection(tasks) {
|
|
|
46
47
|
lines.push(` 进展:${goal.progressNote}`);
|
|
47
48
|
}
|
|
48
49
|
}
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
50
|
+
if (opts?.includeGuidance !== false) {
|
|
51
|
+
lines.push('');
|
|
52
|
+
lines.push('说明:');
|
|
53
|
+
lines.push('- 用户要求继续或话题回归时,可恢复对应任务或先说明进展。');
|
|
54
|
+
lines.push('- 与当前消息无关时,优先处理当前消息,不要强行续做。');
|
|
55
|
+
lines.push('- 完成或放弃时请调用 task_complete / task_drop,保持列表与对话一致。');
|
|
56
|
+
lines.push('- 复杂任务可先 task_create 建目标,再用 task_plan 或 task_create(parent_id) 登记步骤。');
|
|
57
|
+
}
|
|
55
58
|
lines.push('</session_tasks>');
|
|
56
59
|
return lines.join('\n');
|
|
57
60
|
}
|
|
@@ -19,17 +19,32 @@ export interface AgentEventMap {
|
|
|
19
19
|
error: string;
|
|
20
20
|
reason?: string;
|
|
21
21
|
};
|
|
22
|
+
/**
|
|
23
|
+
* 模型调用即将重试(重试窗口对用户可见)
|
|
24
|
+
*
|
|
25
|
+
* 此前重试不产生任何事件:一次 52 分钟停滞期间前端零反馈。
|
|
26
|
+
* `attempt` 从 1 起;`delayMs` 是**即将**等待的退避时长(通知先于等待发出)。
|
|
27
|
+
*/
|
|
28
|
+
'engine.model_retry': {
|
|
29
|
+
attempt: number;
|
|
30
|
+
maxAttempts: number;
|
|
31
|
+
reason: string;
|
|
32
|
+
delayMs: number;
|
|
33
|
+
error: string;
|
|
34
|
+
};
|
|
22
35
|
'iteration.start': Record<string, never>;
|
|
23
36
|
'llm.usage': {
|
|
24
37
|
usage: import('@octopi-agent/core/types/turn.js').TokenUsage;
|
|
25
38
|
};
|
|
26
39
|
'turn.end': {
|
|
40
|
+
/** 本次调用的正文;error=true 时 = 中断前的部分流出(不是回答,不得当回复外发) */
|
|
27
41
|
content?: string;
|
|
28
42
|
userText?: string;
|
|
29
43
|
hasToolCalls: boolean;
|
|
30
44
|
phase: 'pre_tools' | 'final';
|
|
31
45
|
truncated?: boolean;
|
|
32
46
|
stopped?: boolean;
|
|
47
|
+
/** 本次 LLM 调用失败(只出现在重试中途;彻底失败走 agent_end reason='error') */
|
|
33
48
|
error?: boolean;
|
|
34
49
|
usage?: import('@octopi-agent/core/types/turn.js').TokenUsage;
|
|
35
50
|
/** F3 LLM 计时摘要(loop turn_end 透传;Run 页签耗时区消费) */
|
|
@@ -52,6 +67,16 @@ export interface AgentEventMap {
|
|
|
52
67
|
/** 行动简述 */
|
|
53
68
|
purpose?: string;
|
|
54
69
|
};
|
|
70
|
+
/**
|
|
71
|
+
* 工具执行中的部分输出(展示通道;不进对话历史、不参与 afterToolCall 定形)。
|
|
72
|
+
* 载荷已经过 SecurityGuard 出口扫描(与 tool.exec.end 同一判定),违规部分被扣发。
|
|
73
|
+
*/
|
|
74
|
+
'tool.exec.update': {
|
|
75
|
+
toolCallId: string;
|
|
76
|
+
toolName: string;
|
|
77
|
+
/** 部分输出内容(对齐 LoopToolResult.content 语义;发射端已截断) */
|
|
78
|
+
content?: unknown;
|
|
79
|
+
};
|
|
55
80
|
/** ToolEffectPolicy §5.6 效应账本摘要(turn 级;Observer tool.effect) */
|
|
56
81
|
'tool.effect.ledger': {
|
|
57
82
|
entries: number;
|
|
@@ -170,6 +195,12 @@ export interface AgentEventMap {
|
|
|
170
195
|
error: string;
|
|
171
196
|
durationMs?: number;
|
|
172
197
|
};
|
|
198
|
+
/** 摘要请求 cache-miss 旁路/穷尽可观测(F22):no_prefix=无同形前缀,window_guard=前缀放不下改文本化旁路,window_exhausted=最终失败 */
|
|
199
|
+
'context.compact.summarize_fallback': {
|
|
200
|
+
reason?: 'proactive' | 'overflow';
|
|
201
|
+
fallback?: string;
|
|
202
|
+
cached?: boolean;
|
|
203
|
+
};
|
|
173
204
|
/**
|
|
174
205
|
* system prompt 七层装配完成(AssembleManifest 可观测快照)
|
|
175
206
|
* UI 用此事件渲染 Context Runtime;不进入模型输入。
|
|
@@ -217,6 +248,36 @@ export interface AgentEventMap {
|
|
|
217
248
|
};
|
|
218
249
|
/** RunMetricsCollector 快照(reliability → Observer) */
|
|
219
250
|
'run.guard.metrics': import('../../run/reliability/harness-events.js').RunGuardMetricsEvent['data'];
|
|
251
|
+
/** ops P0:jail 意图 × 实测后端(授权 vs 故障的事后判据,run 开始即记录) */
|
|
252
|
+
'ops.jail.state': import('../../extension/execution-environment/effect-policy.js').OpsJailState;
|
|
253
|
+
/** ops P2:run 级降级申报(securityDegraded 快照) */
|
|
254
|
+
'ops.policy.degraded': {
|
|
255
|
+
degradation: string[];
|
|
256
|
+
requestedVsEffective: {
|
|
257
|
+
requestedMode: string;
|
|
258
|
+
mode: string;
|
|
259
|
+
};
|
|
260
|
+
origin: {
|
|
261
|
+
sessionId: string;
|
|
262
|
+
agentId: string;
|
|
263
|
+
runId?: string | null;
|
|
264
|
+
};
|
|
265
|
+
};
|
|
266
|
+
/** ops P2:安全配置漂移 → 拒新 run(§8.4) */
|
|
267
|
+
'ops.config.security_changed': {
|
|
268
|
+
changed: string[];
|
|
269
|
+
action: string;
|
|
270
|
+
/** 旧→新摘要(§7) */
|
|
271
|
+
previousFingerprint: string | null;
|
|
272
|
+
currentFingerprint: string | null;
|
|
273
|
+
/** 谁改的无法从文件判定(agent 写与宿主写同样是磁盘字节)→ 如实 unattributed */
|
|
274
|
+
source: 'unattributed';
|
|
275
|
+
hostAttested: boolean;
|
|
276
|
+
origin: {
|
|
277
|
+
sessionId: string;
|
|
278
|
+
agentId: string;
|
|
279
|
+
};
|
|
280
|
+
};
|
|
220
281
|
'task.created': {
|
|
221
282
|
taskId: string;
|
|
222
283
|
taskType: string;
|
|
@@ -275,12 +336,14 @@ export declare const AgentEvents: {
|
|
|
275
336
|
readonly ENGINE_START: "engine.start";
|
|
276
337
|
readonly ENGINE_END: "engine.end";
|
|
277
338
|
readonly ENGINE_ERROR: "engine.error";
|
|
339
|
+
readonly ENGINE_MODEL_RETRY: "engine.model_retry";
|
|
278
340
|
readonly ITERATION_START: "iteration.start";
|
|
279
341
|
readonly TURN_END: "turn.end";
|
|
280
342
|
/** Runner 收口计时(F3 转正) */
|
|
281
343
|
readonly RUN_TIMING: "run.timing";
|
|
282
344
|
readonly TOOL_EXEC_START: "tool.exec.start";
|
|
283
345
|
readonly TOOL_EXEC_END: "tool.exec.end";
|
|
346
|
+
readonly TOOL_EXEC_UPDATE: "tool.exec.update";
|
|
284
347
|
readonly INJECTION_DETECTED: "injection.detected";
|
|
285
348
|
readonly POLICY_VIOLATED: "policy.violated";
|
|
286
349
|
readonly SENSITIVE_DATA_DETECTED: "sensitive_data.detected";
|
|
@@ -301,6 +364,9 @@ export declare const AgentEvents: {
|
|
|
301
364
|
readonly RUN_SCOPE_MESSAGES: "run.scope.messages";
|
|
302
365
|
readonly RUN_SCOPE_LLM: "run.scope.llm";
|
|
303
366
|
readonly RUN_GUARD_METRICS: "run.guard.metrics";
|
|
367
|
+
readonly OPS_JAIL_STATE: "ops.jail.state";
|
|
368
|
+
readonly OPS_POLICY_DEGRADED: "ops.policy.degraded";
|
|
369
|
+
readonly OPS_CONFIG_SECURITY_CHANGED: "ops.config.security_changed";
|
|
304
370
|
readonly TASK_CREATED: "task.created";
|
|
305
371
|
readonly TASK_STARTED: "task.started";
|
|
306
372
|
readonly TASK_COMPLETED: "task.completed";
|
|
@@ -18,12 +18,14 @@ export const AgentEvents = {
|
|
|
18
18
|
ENGINE_START: 'engine.start',
|
|
19
19
|
ENGINE_END: 'engine.end',
|
|
20
20
|
ENGINE_ERROR: 'engine.error',
|
|
21
|
+
ENGINE_MODEL_RETRY: 'engine.model_retry',
|
|
21
22
|
ITERATION_START: 'iteration.start',
|
|
22
23
|
TURN_END: 'turn.end',
|
|
23
24
|
/** Runner 收口计时(F3 转正) */
|
|
24
25
|
RUN_TIMING: 'run.timing',
|
|
25
26
|
TOOL_EXEC_START: 'tool.exec.start',
|
|
26
27
|
TOOL_EXEC_END: 'tool.exec.end',
|
|
28
|
+
TOOL_EXEC_UPDATE: 'tool.exec.update',
|
|
27
29
|
INJECTION_DETECTED: 'injection.detected',
|
|
28
30
|
POLICY_VIOLATED: 'policy.violated',
|
|
29
31
|
SENSITIVE_DATA_DETECTED: 'sensitive_data.detected',
|
|
@@ -44,6 +46,9 @@ export const AgentEvents = {
|
|
|
44
46
|
RUN_SCOPE_MESSAGES: 'run.scope.messages',
|
|
45
47
|
RUN_SCOPE_LLM: 'run.scope.llm',
|
|
46
48
|
RUN_GUARD_METRICS: 'run.guard.metrics',
|
|
49
|
+
OPS_JAIL_STATE: 'ops.jail.state',
|
|
50
|
+
OPS_POLICY_DEGRADED: 'ops.policy.degraded',
|
|
51
|
+
OPS_CONFIG_SECURITY_CHANGED: 'ops.config.security_changed',
|
|
47
52
|
TASK_CREATED: 'task.created',
|
|
48
53
|
TASK_STARTED: 'task.started',
|
|
49
54
|
TASK_COMPLETED: 'task.completed',
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Path glob compilation — shared by tool glob filters and path denylists.
|
|
3
|
+
*
|
|
4
|
+
* Semantics follow rg/git so that `file_search`'s `glob` argument and
|
|
5
|
+
* `effectPolicy.pathDenylist` cannot drift apart:
|
|
6
|
+
* - `**` crosses directories; `*` and `?` do not cross `/`
|
|
7
|
+
* - a pattern without `/` (for example `*.md`) matches at any depth
|
|
8
|
+
* - `{a,b}` alternatives are supported, including nesting
|
|
9
|
+
*/
|
|
10
|
+
/**
|
|
11
|
+
* Compile a path glob into a regular expression over root-relative paths.
|
|
12
|
+
*
|
|
13
|
+
* @param glob - glob pattern
|
|
14
|
+
* @returns anchored, case-insensitive matcher for a root-relative path
|
|
15
|
+
*/
|
|
16
|
+
export declare function globToPathRegex(glob: string): RegExp;
|
|
17
|
+
/**
|
|
18
|
+
* Normalize a deny pattern into the path dialect the matcher speaks.
|
|
19
|
+
*
|
|
20
|
+
* Windows deployments write separators the way their shell does, so `\` is
|
|
21
|
+
* always a separator here. That makes an escaped literal (`.git\**` meaning
|
|
22
|
+
* "a file literally named `.git*`") impossible to express — acceptable, since a
|
|
23
|
+
* separator is what every real denylist entry means.
|
|
24
|
+
*
|
|
25
|
+
* @param pattern - raw deny pattern from configuration
|
|
26
|
+
* @returns pattern using `/` separators
|
|
27
|
+
*/
|
|
28
|
+
export declare function normalizeDenyPattern(pattern: string): string;
|
|
29
|
+
/**
|
|
30
|
+
* Reject deny patterns that can never match a root-relative path.
|
|
31
|
+
*
|
|
32
|
+
* A pattern that silently matches nothing is worse than a startup error: the
|
|
33
|
+
* deployment keeps believing it is protected. Shapes rejected here are all
|
|
34
|
+
* spellings that look meaningful but cannot match (`/x` anchors outside the
|
|
35
|
+
* root, `x/` never matches a resolved file, `../x` has no candidate).
|
|
36
|
+
*
|
|
37
|
+
* @param pattern - raw deny pattern from configuration
|
|
38
|
+
*/
|
|
39
|
+
export declare function validateDenyPattern(pattern: string): void;
|
|
40
|
+
/**
|
|
41
|
+
* Whether a root-relative path matches any denylist pattern.
|
|
42
|
+
*
|
|
43
|
+
* Both the full relative path and the file name are tested, so `.env*` and
|
|
44
|
+
* `.git/**` can coexist without the caller deciding which form a pattern means.
|
|
45
|
+
* Invalid patterns are the caller's mistake and throw: silently ignoring a
|
|
46
|
+
* typo'd security pattern would leave the deployment believing it is protected.
|
|
47
|
+
*
|
|
48
|
+
* @param relativePath - path relative to the containing root, using `/`
|
|
49
|
+
* @param patterns - denylist globs
|
|
50
|
+
* @returns true when any pattern matches
|
|
51
|
+
*/
|
|
52
|
+
export declare function matchesDenyPattern(relativePath: string, patterns: readonly string[]): boolean;
|
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Path glob compilation — shared by tool glob filters and path denylists.
|
|
3
|
+
*
|
|
4
|
+
* Semantics follow rg/git so that `file_search`'s `glob` argument and
|
|
5
|
+
* `effectPolicy.pathDenylist` cannot drift apart:
|
|
6
|
+
* - `**` crosses directories; `*` and `?` do not cross `/`
|
|
7
|
+
* - a pattern without `/` (for example `*.md`) matches at any depth
|
|
8
|
+
* - `{a,b}` alternatives are supported, including nesting
|
|
9
|
+
*/
|
|
10
|
+
/**
|
|
11
|
+
* Compile a path glob into a regular expression over root-relative paths.
|
|
12
|
+
*
|
|
13
|
+
* @param glob - glob pattern
|
|
14
|
+
* @returns anchored, case-insensitive matcher for a root-relative path
|
|
15
|
+
*/
|
|
16
|
+
export function globToPathRegex(glob) {
|
|
17
|
+
const trimmed = glob.trim();
|
|
18
|
+
if (!trimmed)
|
|
19
|
+
throw new Error('glob must be non-empty');
|
|
20
|
+
// Compiled patterns are pure functions of the pattern text, and denylists are
|
|
21
|
+
// re-evaluated for every walked file, so memoize instead of recompiling.
|
|
22
|
+
const cached = COMPILED.get(trimmed);
|
|
23
|
+
if (cached)
|
|
24
|
+
return cached;
|
|
25
|
+
const normalized = trimmed.includes('/') ? trimmed : `**/${trimmed}`;
|
|
26
|
+
const regex = new RegExp(`^${globToSource(normalized)}$`, 'i');
|
|
27
|
+
if (COMPILED.size >= COMPILE_CACHE_LIMIT)
|
|
28
|
+
COMPILED.clear();
|
|
29
|
+
COMPILED.set(trimmed, regex);
|
|
30
|
+
return regex;
|
|
31
|
+
}
|
|
32
|
+
const COMPILED = new Map();
|
|
33
|
+
const COMPILE_CACHE_LIMIT = 512;
|
|
34
|
+
/**
|
|
35
|
+
* Normalize a deny pattern into the path dialect the matcher speaks.
|
|
36
|
+
*
|
|
37
|
+
* Windows deployments write separators the way their shell does, so `\` is
|
|
38
|
+
* always a separator here. That makes an escaped literal (`.git\**` meaning
|
|
39
|
+
* "a file literally named `.git*`") impossible to express — acceptable, since a
|
|
40
|
+
* separator is what every real denylist entry means.
|
|
41
|
+
*
|
|
42
|
+
* @param pattern - raw deny pattern from configuration
|
|
43
|
+
* @returns pattern using `/` separators
|
|
44
|
+
*/
|
|
45
|
+
export function normalizeDenyPattern(pattern) {
|
|
46
|
+
return pattern.trim().split('\\').join('/');
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* Reject deny patterns that can never match a root-relative path.
|
|
50
|
+
*
|
|
51
|
+
* A pattern that silently matches nothing is worse than a startup error: the
|
|
52
|
+
* deployment keeps believing it is protected. Shapes rejected here are all
|
|
53
|
+
* spellings that look meaningful but cannot match (`/x` anchors outside the
|
|
54
|
+
* root, `x/` never matches a resolved file, `../x` has no candidate).
|
|
55
|
+
*
|
|
56
|
+
* @param pattern - raw deny pattern from configuration
|
|
57
|
+
*/
|
|
58
|
+
export function validateDenyPattern(pattern) {
|
|
59
|
+
const normalized = normalizeDenyPattern(pattern);
|
|
60
|
+
if (!normalized)
|
|
61
|
+
throw new Error('pathDenylist: pattern must be non-empty');
|
|
62
|
+
if (normalized.startsWith('/')) {
|
|
63
|
+
throw new Error(`pathDenylist: "${pattern}" must be root-relative (drop the leading "/")`);
|
|
64
|
+
}
|
|
65
|
+
if (normalized.endsWith('/')) {
|
|
66
|
+
throw new Error(`pathDenylist: "${pattern}" must not end with a separator`);
|
|
67
|
+
}
|
|
68
|
+
if (normalized.split('/').some((segment) => segment === '..' || segment === '.')) {
|
|
69
|
+
throw new Error(`pathDenylist: "${pattern}" must not contain "." or ".." segments`);
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* Compile a normalized glob fragment into regex source.
|
|
74
|
+
*
|
|
75
|
+
* @param glob - glob containing path separators
|
|
76
|
+
* @returns regex source without anchors
|
|
77
|
+
*/
|
|
78
|
+
function globToSource(glob) {
|
|
79
|
+
let out = '';
|
|
80
|
+
let index = 0;
|
|
81
|
+
while (index < glob.length) {
|
|
82
|
+
const char = glob[index];
|
|
83
|
+
// `\*`, `\?` and friends are literals.
|
|
84
|
+
if (char === '\\' && index + 1 < glob.length && '*?[]{}\\/!'.includes(glob[index + 1])) {
|
|
85
|
+
out += escapeRegex(glob[index + 1]);
|
|
86
|
+
index += 2;
|
|
87
|
+
continue;
|
|
88
|
+
}
|
|
89
|
+
if (char === '*' && glob[index + 1] === '*') {
|
|
90
|
+
index += 2;
|
|
91
|
+
if (glob[index] === '/') {
|
|
92
|
+
index += 1;
|
|
93
|
+
// `**/` → any depth prefix, including zero segments
|
|
94
|
+
out += '(?:.*/)?';
|
|
95
|
+
}
|
|
96
|
+
else {
|
|
97
|
+
out += '.*';
|
|
98
|
+
}
|
|
99
|
+
continue;
|
|
100
|
+
}
|
|
101
|
+
if (char === '*') {
|
|
102
|
+
index += 1;
|
|
103
|
+
out += '[^/]*';
|
|
104
|
+
continue;
|
|
105
|
+
}
|
|
106
|
+
if (char === '?') {
|
|
107
|
+
index += 1;
|
|
108
|
+
out += '[^/]';
|
|
109
|
+
continue;
|
|
110
|
+
}
|
|
111
|
+
if (char === '{') {
|
|
112
|
+
const end = findBraceEnd(glob, index);
|
|
113
|
+
if (end === -1) {
|
|
114
|
+
out += '\\{';
|
|
115
|
+
index += 1;
|
|
116
|
+
continue;
|
|
117
|
+
}
|
|
118
|
+
const alternatives = splitBraceAlternatives(glob.slice(index + 1, end));
|
|
119
|
+
out += `(?:${alternatives.map((alt) => globToSource(alt)).join('|')})`;
|
|
120
|
+
index = end + 1;
|
|
121
|
+
continue;
|
|
122
|
+
}
|
|
123
|
+
if ('.+^$()|[]'.includes(char)) {
|
|
124
|
+
out += `\\${char}`;
|
|
125
|
+
}
|
|
126
|
+
else {
|
|
127
|
+
out += char;
|
|
128
|
+
}
|
|
129
|
+
index += 1;
|
|
130
|
+
}
|
|
131
|
+
return out;
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* Find the `}` matching the `{` at `openIndex`, skipping nesting.
|
|
135
|
+
*
|
|
136
|
+
* @param glob - glob string
|
|
137
|
+
* @param openIndex - index of `{`
|
|
138
|
+
* @returns index of the matching `}`; -1 when unbalanced
|
|
139
|
+
*/
|
|
140
|
+
function findBraceEnd(glob, openIndex) {
|
|
141
|
+
let depth = 0;
|
|
142
|
+
for (let index = openIndex; index < glob.length; index += 1) {
|
|
143
|
+
if (glob[index] === '{')
|
|
144
|
+
depth += 1;
|
|
145
|
+
else if (glob[index] === '}') {
|
|
146
|
+
depth -= 1;
|
|
147
|
+
if (depth === 0)
|
|
148
|
+
return index;
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
return -1;
|
|
152
|
+
}
|
|
153
|
+
/**
|
|
154
|
+
* Split top-level comma alternatives inside braces.
|
|
155
|
+
*
|
|
156
|
+
* @param body - contents between braces
|
|
157
|
+
* @returns alternatives
|
|
158
|
+
*/
|
|
159
|
+
function splitBraceAlternatives(body) {
|
|
160
|
+
const alternatives = [];
|
|
161
|
+
let depth = 0;
|
|
162
|
+
let current = '';
|
|
163
|
+
for (const char of body) {
|
|
164
|
+
if (char === '{')
|
|
165
|
+
depth += 1;
|
|
166
|
+
if (char === '}')
|
|
167
|
+
depth -= 1;
|
|
168
|
+
if (char === ',' && depth === 0) {
|
|
169
|
+
alternatives.push(current);
|
|
170
|
+
current = '';
|
|
171
|
+
continue;
|
|
172
|
+
}
|
|
173
|
+
current += char;
|
|
174
|
+
}
|
|
175
|
+
alternatives.push(current);
|
|
176
|
+
return alternatives;
|
|
177
|
+
}
|
|
178
|
+
/**
|
|
179
|
+
* Escape a single character for use in a regex literal.
|
|
180
|
+
*
|
|
181
|
+
* @param char - character to escape
|
|
182
|
+
* @returns escaped character
|
|
183
|
+
*/
|
|
184
|
+
function escapeRegex(char) {
|
|
185
|
+
return char.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
186
|
+
}
|
|
187
|
+
/**
|
|
188
|
+
* Whether a root-relative path matches any denylist pattern.
|
|
189
|
+
*
|
|
190
|
+
* Both the full relative path and the file name are tested, so `.env*` and
|
|
191
|
+
* `.git/**` can coexist without the caller deciding which form a pattern means.
|
|
192
|
+
* Invalid patterns are the caller's mistake and throw: silently ignoring a
|
|
193
|
+
* typo'd security pattern would leave the deployment believing it is protected.
|
|
194
|
+
*
|
|
195
|
+
* @param relativePath - path relative to the containing root, using `/`
|
|
196
|
+
* @param patterns - denylist globs
|
|
197
|
+
* @returns true when any pattern matches
|
|
198
|
+
*/
|
|
199
|
+
export function matchesDenyPattern(relativePath, patterns) {
|
|
200
|
+
if (patterns.length === 0)
|
|
201
|
+
return false;
|
|
202
|
+
const normalized = relativePath.split('\\').join('/');
|
|
203
|
+
const segments = normalized.split('/').filter(Boolean);
|
|
204
|
+
// Test the full path *and every suffix*, so a pattern like `.git/**` denies a
|
|
205
|
+
// `.git` directory at any depth. Anchoring only at the root would let
|
|
206
|
+
// `pkg/.git/config` through, which for a security denylist is a silent hole.
|
|
207
|
+
const candidates = [normalized];
|
|
208
|
+
for (let index = 1; index < segments.length; index += 1) {
|
|
209
|
+
candidates.push(segments.slice(index).join('/'));
|
|
210
|
+
}
|
|
211
|
+
const name = segments[segments.length - 1] ?? normalized;
|
|
212
|
+
if (!candidates.includes(name))
|
|
213
|
+
candidates.push(name);
|
|
214
|
+
return patterns.some((pattern) => {
|
|
215
|
+
const matcher = globToPathRegex(normalizeDenyPattern(pattern));
|
|
216
|
+
return candidates.some((candidate) => matcher.test(candidate));
|
|
217
|
+
});
|
|
218
|
+
}
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Path containment primitives — shared by tool execution and effect auditing
|
|
3
|
+
*
|
|
4
|
+
* Containment is a cross-cutting mechanism, not a policy owned by one domain:
|
|
5
|
+
* the tools domain decides *what* may be touched (`pathRoots`, `containment`),
|
|
6
|
+
* while the execution-environment domain decides *what gets recorded*. Both
|
|
7
|
+
* need the same answer to "is this path under that root", and both need it in
|
|
8
|
+
* real coordinates — a purely lexical comparison lets a symlink inside a root
|
|
9
|
+
* reach outside it.
|
|
10
|
+
*
|
|
11
|
+
* These helpers live in `shared/` so that no domain has to import another
|
|
12
|
+
* domain's internals to get correct containment. They are foundation code:
|
|
13
|
+
* no policy defaults, no product decisions.
|
|
14
|
+
*/
|
|
15
|
+
/**
|
|
16
|
+
* Resolve a path that may not exist yet to its real location.
|
|
17
|
+
*
|
|
18
|
+
* `realpathSync` throws for a missing target, but creating a new file is a
|
|
19
|
+
* normal operation. Walk up to the deepest existing ancestor, resolve that,
|
|
20
|
+
* and re-append the remaining segments. `resolve()` already folded `..`, so the
|
|
21
|
+
* appended tail cannot introduce a new escape.
|
|
22
|
+
*
|
|
23
|
+
* A missing segment that *does* exist as a directory entry is not treated as
|
|
24
|
+
* "about to be created": that is a dangling symlink or a link loop, and letting
|
|
25
|
+
* it through would allow the following open/write to follow it out of the root.
|
|
26
|
+
* `lstatSync` does not follow the final component, which separates the cases.
|
|
27
|
+
*
|
|
28
|
+
* @param abs - absolute, lexically normalized path
|
|
29
|
+
* @returns real path, or null when it cannot be resolved safely
|
|
30
|
+
*/
|
|
31
|
+
export declare function realpathAllowMissing(abs: string): string | null;
|
|
32
|
+
/**
|
|
33
|
+
* Containment over already-normalized paths (no filesystem access).
|
|
34
|
+
*
|
|
35
|
+
* Use this only when both sides are already real paths; otherwise prefer
|
|
36
|
+
* {@link isPathUnderRoots}, which resolves them first.
|
|
37
|
+
*
|
|
38
|
+
* Windows drive letters are compared case-insensitively, matching how the
|
|
39
|
+
* effect policy treats volume names.
|
|
40
|
+
*
|
|
41
|
+
* @param absPath - path already resolved to its real form
|
|
42
|
+
* @param roots - roots already resolved to their real form
|
|
43
|
+
* @returns whether the path is one of the roots or under one
|
|
44
|
+
*/
|
|
45
|
+
export declare function lexicalUnderRoots(absPath: string, roots: string[]): boolean;
|
|
46
|
+
/**
|
|
47
|
+
* Whether a path falls under any of the given roots, in real coordinates.
|
|
48
|
+
*
|
|
49
|
+
* Both sides are resolved: comparing a resolved target against an unresolved
|
|
50
|
+
* root would wrongly deny legitimate paths whenever the root is itself an alias
|
|
51
|
+
* (macOS `/var` → `/private/var`, a symlinked `$HOME`). A path that cannot be
|
|
52
|
+
* resolved falls back to its lexical form, so this only ever answers "is it
|
|
53
|
+
* inside", never "is it safe to operate on" — callers that need the resolved
|
|
54
|
+
* path must use their own resolution step.
|
|
55
|
+
*
|
|
56
|
+
* @param absPath - path to test
|
|
57
|
+
* @param roots - allowed roots
|
|
58
|
+
* @returns true when the path is one of the roots or under one
|
|
59
|
+
*/
|
|
60
|
+
export declare function isPathUnderRoots(absPath: string, roots: readonly string[]): boolean;
|
|
61
|
+
/**
|
|
62
|
+
* Whether the final path component is a symbolic link, without following it.
|
|
63
|
+
*
|
|
64
|
+
* `lstat` inspects the entry itself, so a dangling link still reports `true` —
|
|
65
|
+
* which is what a write guard needs: an unresolvable link is exactly the case
|
|
66
|
+
* where a later open would follow it somewhere unintended.
|
|
67
|
+
*
|
|
68
|
+
* @param path - path to inspect
|
|
69
|
+
* @returns true when the entry exists and is a symlink
|
|
70
|
+
*/
|
|
71
|
+
export declare function isFinalSymlink(path: string): boolean;
|
|
72
|
+
/**
|
|
73
|
+
* Read a file refusing to traverse a symlink at the final component.
|
|
74
|
+
*
|
|
75
|
+
* Resolving containment already returns a real path, so normally the final
|
|
76
|
+
* component is not a link. If it is one at open time, something replaced it
|
|
77
|
+
* between the containment check and this open; `O_NOFOLLOW` makes the kernel
|
|
78
|
+
* refuse instead of following it (`ELOOP`).
|
|
79
|
+
*
|
|
80
|
+
* @param path - absolute path, normally already resolved
|
|
81
|
+
* @param encoding - text encoding
|
|
82
|
+
* @returns file contents
|
|
83
|
+
*/
|
|
84
|
+
export declare function readFileNoFollow(path: string, encoding: 'utf8'): Promise<string>;
|