@octopi-agent/engine 0.86.38 → 0.97.15
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 +43 -1
- package/dist/config-schema/agent.js +12 -5
- package/dist/config-schema/context.d.ts +7 -2
- package/dist/config-schema/context.js +8 -0
- package/dist/config-schema/engine.d.ts +110 -8
- package/dist/config-schema/governance.d.ts +43 -1
- package/dist/config-schema/governance.js +160 -2
- package/dist/config-schema/models.d.ts +7 -4
- 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-schema/shared.d.ts +3 -0
- package/dist/config-schema/shared.js +12 -0
- package/dist/config-schema/substrate.d.ts +1 -1
- package/dist/config.d.ts +60 -13
- package/dist/config.js +81 -78
- 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 +18 -3
- package/dist/harness/agent/builder.js +42 -17
- package/dist/harness/agent/config-bridge.d.ts +5 -0
- package/dist/harness/agent/config-bridge.js +7 -1
- package/dist/harness/agent/config-integrity.d.ts +72 -0
- package/dist/harness/agent/config-integrity.js +146 -0
- package/dist/harness/agent/tool-purpose.d.ts +9 -1
- package/dist/harness/agent/tool-purpose.js +11 -2
- package/dist/harness/agent/wire-agent-builder.js +11 -3
- package/dist/harness/collaboration/autonomous-subsystem/boundary/validator.d.ts +11 -1
- package/dist/harness/collaboration/autonomous-subsystem/boundary/validator.js +11 -1
- package/dist/harness/collaboration/autonomous-subsystem/loader.d.ts +13 -0
- package/dist/harness/collaboration/autonomous-subsystem/loader.js +16 -1
- package/dist/harness/collaboration/autonomous-subsystem/runtime.d.ts +4 -0
- package/dist/harness/collaboration/autonomous-subsystem/runtime.js +3 -1
- package/dist/harness/collaboration/autonomous-subsystem/think/executor.js +3 -1
- 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/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 +198 -53
- package/dist/harness/context/hybrid-compressor.js +6 -0
- package/dist/harness/context/layer-types.d.ts +36 -0
- package/dist/harness/context/layer-types.js +38 -0
- 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/root-instructions.js +1 -1
- package/dist/harness/context/summarize.d.ts +2 -0
- package/dist/harness/context/summarize.js +7 -2
- package/dist/harness/context/system-prompt-assembler.js +10 -4
- package/dist/harness/context/tool-result-aging.js +2 -2
- package/dist/harness/context/truncate-compressor.js +7 -0
- package/dist/harness/context/turn-envelope.d.ts +4 -3
- package/dist/harness/context/turn-envelope.js +4 -3
- 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 +133 -4
- package/dist/harness/extension/execution-environment/effect-policy.js +263 -14
- 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/isolation.js +5 -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 +200 -0
- package/dist/harness/extension/execution-environment/ops-audit.js +338 -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 +264 -29
- 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/plugin-ecosystem/channel-types.d.ts +5 -0
- package/dist/harness/extension/plugin-ecosystem/tools/allowlisted-run.d.ts +6 -0
- package/dist/harness/extension/plugin-ecosystem/tools/allowlisted-run.js +50 -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 +53 -2
- package/dist/harness/extension/plugin-ecosystem/tools/file-search.js +10 -17
- package/dist/harness/extension/plugin-ecosystem/tools/git-runner.d.ts +31 -0
- package/dist/harness/extension/plugin-ecosystem/tools/git-runner.js +104 -0
- package/dist/harness/extension/plugin-ecosystem/tools/git-status-snapshot.d.ts +111 -0
- package/dist/harness/extension/plugin-ecosystem/tools/git-status-snapshot.js +197 -0
- package/dist/harness/extension/plugin-ecosystem/tools/git-tools.d.ts +8 -8
- package/dist/harness/extension/plugin-ecosystem/tools/git-tools.js +9 -100
- package/dist/harness/extension/plugin-ecosystem/tools/index.d.ts +6 -0
- package/dist/harness/extension/plugin-ecosystem/tools/index.js +4 -0
- 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/temp-path.d.ts +9 -0
- package/dist/harness/governance/security/temp-path.js +13 -2
- package/dist/harness/governance/session-acl/seed-roles.js +14 -0
- package/dist/harness/index.d.ts +4 -0
- package/dist/harness/index.js +3 -0
- package/dist/harness/knowledge/file-identity.d.ts +8 -0
- package/dist/harness/knowledge/file-identity.js +26 -1
- package/dist/harness/knowledge/fts.js +1 -2
- package/dist/harness/knowledge/grounding.js +5 -5
- package/dist/harness/knowledge/index-store.d.ts +31 -4
- package/dist/harness/knowledge/index-store.js +180 -48
- package/dist/harness/knowledge/ingest.d.ts +115 -115
- package/dist/harness/knowledge/ingest.js +150 -150
- package/dist/harness/knowledge/knowledge-serve-child.js +1 -1
- package/dist/harness/knowledge/purge.js +4 -1
- package/dist/harness/memory/backfill-coverage.js +3 -1
- package/dist/harness/memory/sqlite/keyword-search.d.ts +1 -0
- package/dist/harness/memory/sqlite/keyword-search.js +4 -3
- package/dist/harness/observability/observer/hub.js +38 -1
- package/dist/harness/observability/observer/run-snapshot.js +1 -0
- package/dist/harness/observability/observer/types.d.ts +27 -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 +31 -0
- package/dist/harness/run/runner.d.ts +132 -2
- package/dist/harness/run/runner.js +679 -60
- package/dist/harness/session/attachments/llm-intent.js +2 -1
- package/dist/harness/session/history/port.js +15 -5
- package/dist/harness/session/in-memory-store.d.ts +5 -0
- package/dist/harness/session/in-memory-store.js +33 -2
- package/dist/harness/session/tasks/render.d.ts +4 -1
- package/dist/harness/session/tasks/render.js +10 -7
- package/dist/harness/session/title.js +25 -9
- package/dist/harness/shared/events/agent-event-map.d.ts +92 -0
- package/dist/harness/shared/events/agent-event-map.js +7 -0
- package/dist/index.d.ts +6 -4
- package/dist/index.js +4 -3
- 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/observability/run-telemetry.d.ts +8 -0
- package/dist/integration/observability/run-telemetry.js +31 -8
- package/dist/integration/observability/trace-collector.js +26 -4
- package/dist/integration/observability/trace-events.d.ts +1 -0
- package/dist/integration/observability/trace-events.js +2 -0
- package/dist/integration/observability/trace-logger.js +27 -17
- 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.d.ts +19 -1
- package/dist/integration/storage/jsonl.js +100 -4
- package/dist/paths.d.ts +19 -0
- package/dist/paths.js +38 -1
- package/dist/subsystems/cognition-steward/conceptualize/handler.js +1 -1
- package/dist/subsystems/memory-steward/backfill/handler.js +1 -1
- package/dist/subsystems/safety-guard/config.yaml +3 -1
- package/dist/subsystems/wisdom-steward/formation/handler.js +1 -1
- package/package.json +3 -2
|
@@ -0,0 +1,418 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 独立提权执行通道(ops P3,`arch/ops-privileged-mode.md` §5 P3 / §8)
|
|
3
|
+
*
|
|
4
|
+
* 设计要点(拍板 + 评审修复):
|
|
5
|
+
* - **提权走独立通道,不与牢笼抢轴**:引擎侧 `execFile` 执行完整 argv——不经 shell
|
|
6
|
+
* (无插值/无通配)、不包 jail、env 消毒、cwd 钉住(规则显式或 `/`,**不受 agent
|
|
7
|
+
* 控制**)、超时 + 真树杀(detached 进程组)。
|
|
8
|
+
* - **全等匹配**(effect-policy `matchEscalationRule`):`cmd` 绝对路径 + `args` 逐项
|
|
9
|
+
* 全等;执行即所配 argv,无任何隐式前缀。
|
|
10
|
+
* - **二进制不可换(TOCTOU 护栏)**:对规则的**每一个有效目标**(`via: sudo` 形态下是
|
|
11
|
+
* sudo 之后的真实二进制,不只是 `cmd`)检查:不在 agent 可写面(含符号链接解析后)、
|
|
12
|
+
* 文件与父目录链均不可被 agent uid / 组 / 世界写(可写目录 + rename 即可换二进制)。
|
|
13
|
+
* - **启动期探测,拿不到即拒绝启动**(拍板 #5):`via: sudo` 跑 `sudo -n true`(绝对
|
|
14
|
+
* 路径);`via: direct` 断言高权限(geteuid 0 / win32 `fsutil dirty query`)。
|
|
15
|
+
* 探测证明「通道可用」,不证明「每条规则被 sudoers 授权」(文档如实声明)。
|
|
16
|
+
*/
|
|
17
|
+
import { spawn } from 'node:child_process';
|
|
18
|
+
import { statSync, realpathSync } from 'node:fs';
|
|
19
|
+
import { homedir, tmpdir } from 'node:os';
|
|
20
|
+
import { dirname, isAbsolute, resolve, sep } from 'node:path';
|
|
21
|
+
import { killProcessTree, scrubEnv } from './process-isolation.js';
|
|
22
|
+
function envForExec() {
|
|
23
|
+
// root 态下 PATH/HOME 都是注入面(per-user 配置、可写 PATH 目录)——钉死系统值。
|
|
24
|
+
// 其余一律不透传(凭证/注入面收敛)。
|
|
25
|
+
if (process.platform === 'win32') {
|
|
26
|
+
return scrubEnv({
|
|
27
|
+
SystemRoot: process.env.SystemRoot ?? 'C:\\Windows',
|
|
28
|
+
WINDIR: process.env.WINDIR ?? 'C:\\Windows',
|
|
29
|
+
PATH: `${process.env.SystemRoot ?? 'C:\\Windows'}\\System32`,
|
|
30
|
+
});
|
|
31
|
+
}
|
|
32
|
+
return scrubEnv({ PATH: '/usr/sbin:/usr/bin:/sbin:/bin', HOME: '/', LANG: 'C' });
|
|
33
|
+
}
|
|
34
|
+
const OUTPUT_CAP = 128 * 1024;
|
|
35
|
+
function capOutput(text) {
|
|
36
|
+
return text.length > OUTPUT_CAP ? `${text.slice(0, OUTPUT_CAP)}\n…[truncated ${text.length - OUTPUT_CAP} chars]` : text;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* 执行一条已匹配的提权命令(不经 shell、不包 jail、cwd 钉住)。
|
|
40
|
+
*
|
|
41
|
+
* @param options - cmd/args(完整 argv)、via、cwd、timeoutMs
|
|
42
|
+
* @returns 执行结果(spawn 从未成功时 executed=false)
|
|
43
|
+
*/
|
|
44
|
+
export function runPrivilegedExec(options) {
|
|
45
|
+
const started = Date.now();
|
|
46
|
+
const timeoutMs = options.timeoutMs ?? 120_000;
|
|
47
|
+
return new Promise((resolveP) => {
|
|
48
|
+
let settled = false;
|
|
49
|
+
let stdout = '';
|
|
50
|
+
let stderr = '';
|
|
51
|
+
let timedOut = false;
|
|
52
|
+
let aborted = false;
|
|
53
|
+
let killer;
|
|
54
|
+
let onAbort;
|
|
55
|
+
const done = (result) => {
|
|
56
|
+
if (settled)
|
|
57
|
+
return;
|
|
58
|
+
settled = true;
|
|
59
|
+
if (killer)
|
|
60
|
+
clearTimeout(killer);
|
|
61
|
+
if (onAbort)
|
|
62
|
+
options.abortSignal?.removeEventListener('abort', onAbort);
|
|
63
|
+
resolveP(result);
|
|
64
|
+
};
|
|
65
|
+
try {
|
|
66
|
+
// spawn(不是 execFile):detached 只有 spawn 才转发——独立进程组是真树杀的前提
|
|
67
|
+
const child = spawn(options.cmd, options.args, {
|
|
68
|
+
cwd: options.cwd ?? '/',
|
|
69
|
+
env: envForExec(),
|
|
70
|
+
windowsHide: true,
|
|
71
|
+
detached: process.platform !== 'win32',
|
|
72
|
+
stdio: ['ignore', 'pipe', 'pipe'],
|
|
73
|
+
});
|
|
74
|
+
child.stdout?.setEncoding('utf8');
|
|
75
|
+
child.stderr?.setEncoding('utf8');
|
|
76
|
+
child.stdout?.on('data', (chunk) => {
|
|
77
|
+
if (stdout.length < OUTPUT_CAP * 2)
|
|
78
|
+
stdout += chunk;
|
|
79
|
+
});
|
|
80
|
+
child.stderr?.on('data', (chunk) => {
|
|
81
|
+
if (stderr.length < OUTPUT_CAP * 2)
|
|
82
|
+
stderr += chunk;
|
|
83
|
+
});
|
|
84
|
+
killer = setTimeout(() => {
|
|
85
|
+
timedOut = true;
|
|
86
|
+
try {
|
|
87
|
+
killProcessTree(child);
|
|
88
|
+
}
|
|
89
|
+
catch {
|
|
90
|
+
// 树杀失败退化单杀:至少收回直接子进程,结果侧如实 timedOut
|
|
91
|
+
try {
|
|
92
|
+
child.kill('SIGKILL');
|
|
93
|
+
}
|
|
94
|
+
catch {
|
|
95
|
+
// 进程已死:结果照常出
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
}, timeoutMs);
|
|
99
|
+
killer.unref?.();
|
|
100
|
+
// run 中止即时树杀(与超时同一收回路径):外部中止不等 timeoutMs 兜底
|
|
101
|
+
onAbort = () => {
|
|
102
|
+
aborted = true;
|
|
103
|
+
try {
|
|
104
|
+
killProcessTree(child);
|
|
105
|
+
}
|
|
106
|
+
catch {
|
|
107
|
+
try {
|
|
108
|
+
child.kill('SIGKILL');
|
|
109
|
+
}
|
|
110
|
+
catch {
|
|
111
|
+
// 进程已死:结果照常出
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
};
|
|
115
|
+
if (options.abortSignal) {
|
|
116
|
+
if (options.abortSignal.aborted)
|
|
117
|
+
onAbort();
|
|
118
|
+
else
|
|
119
|
+
options.abortSignal.addEventListener('abort', onAbort, { once: true });
|
|
120
|
+
}
|
|
121
|
+
child.on('error', (err) => {
|
|
122
|
+
// spawn 从未成功(ENOENT/EPERM…)= 未执行,区别于执行了但非零退出
|
|
123
|
+
done({
|
|
124
|
+
executed: false,
|
|
125
|
+
exitCode: null,
|
|
126
|
+
stdout: capOutput(stdout),
|
|
127
|
+
stderr: capOutput(stderr || errText(err)),
|
|
128
|
+
durationMs: Date.now() - started,
|
|
129
|
+
timedOut,
|
|
130
|
+
...(aborted ? { aborted: true } : {}),
|
|
131
|
+
});
|
|
132
|
+
});
|
|
133
|
+
// 收 `exit` 而非 `close`:后台子孙继承 stdio 管道时 close 会被吊住不返回
|
|
134
|
+
child.on('exit', (code) => {
|
|
135
|
+
// 命令结束即树杀(D1 同语义):特权通道不留孤儿(后台 `&` 进程/孙进程);
|
|
136
|
+
// 守护型目标(systemctl 等)已 setsid 自立组,不受此杀
|
|
137
|
+
try {
|
|
138
|
+
killProcessTree(child);
|
|
139
|
+
}
|
|
140
|
+
catch {
|
|
141
|
+
// 组已空或无权限:无孤儿可杀,照常出结果
|
|
142
|
+
}
|
|
143
|
+
done({
|
|
144
|
+
executed: true,
|
|
145
|
+
exitCode: code,
|
|
146
|
+
stdout: capOutput(stdout),
|
|
147
|
+
stderr: capOutput(stderr),
|
|
148
|
+
durationMs: Date.now() - started,
|
|
149
|
+
timedOut,
|
|
150
|
+
...(aborted ? { aborted: true } : {}),
|
|
151
|
+
});
|
|
152
|
+
});
|
|
153
|
+
}
|
|
154
|
+
catch (err) {
|
|
155
|
+
// spawn 同步抛出:同「未执行」语义,绝不冒充执行结果
|
|
156
|
+
done({
|
|
157
|
+
executed: false,
|
|
158
|
+
exitCode: null,
|
|
159
|
+
stdout: '',
|
|
160
|
+
stderr: errText(err),
|
|
161
|
+
durationMs: Date.now() - started,
|
|
162
|
+
timedOut,
|
|
163
|
+
});
|
|
164
|
+
}
|
|
165
|
+
});
|
|
166
|
+
}
|
|
167
|
+
function errText(err) {
|
|
168
|
+
return err instanceof Error ? err.message : String(err);
|
|
169
|
+
}
|
|
170
|
+
/**
|
|
171
|
+
* 列出规则的**有效提权目标**(TOCTOU 护栏逐个检查的对象)。
|
|
172
|
+
*
|
|
173
|
+
* `via: sudo` 形态的真正目标是 sudo 之后的二进制(`args[1]`)——只查 `cmd` 等于不查。
|
|
174
|
+
*
|
|
175
|
+
* @param rule - 白名单规则
|
|
176
|
+
* @param via - 通道形态
|
|
177
|
+
* @returns 目标路径列表;形态非法时 `invalid` 给出原因
|
|
178
|
+
*/
|
|
179
|
+
export function escalationRuleTargets(rule, via) {
|
|
180
|
+
const args = rule.args ?? [];
|
|
181
|
+
if (via === 'sudo') {
|
|
182
|
+
if (args[0] !== '-n') {
|
|
183
|
+
return { invalid: `via=sudo rules must spell \`sudo -n\` explicitly (args[0] must be "-n"), got ${JSON.stringify(args[0])}` };
|
|
184
|
+
}
|
|
185
|
+
const target = args[1];
|
|
186
|
+
if (target === undefined || !isAbsolute(target)) {
|
|
187
|
+
return { invalid: `via=sudo rules need the real target as args[1] (absolute path), got ${JSON.stringify(target)}` };
|
|
188
|
+
}
|
|
189
|
+
return { targets: [rule.cmd, target] };
|
|
190
|
+
}
|
|
191
|
+
return { targets: [rule.cmd] };
|
|
192
|
+
}
|
|
193
|
+
/**
|
|
194
|
+
* TOCTOU 护栏:目标二进制不可被换(agent 可写面 / 文件或父目录可写 → 拒绝)。
|
|
195
|
+
*
|
|
196
|
+
* 检查口径(评审修复):
|
|
197
|
+
* - 路径与其 `realpath` 都做可写面判定(符号链接穿透);
|
|
198
|
+
* - 文件本体 **与父目录链**都不可写(可写目录 + rename 即可替换 0555 文件);
|
|
199
|
+
* - 目标不存在(可后装)时仅当父目录链安全才放行。
|
|
200
|
+
*
|
|
201
|
+
* @param target - 目标二进制绝对路径
|
|
202
|
+
* @param writableRoots - agent 可写根(workspace/home/tmp/transactionRoots/…)
|
|
203
|
+
* @returns 违规原因;通过返回 null
|
|
204
|
+
*/
|
|
205
|
+
export function checkEscalationBinary(target, writableRoots) {
|
|
206
|
+
if (!isAbsolute(target))
|
|
207
|
+
return `path must be absolute, got ${JSON.stringify(target)}`;
|
|
208
|
+
const raw = resolve(target);
|
|
209
|
+
const roots = writableRoots.map((r) => resolve(r));
|
|
210
|
+
const underRoots = (p) => {
|
|
211
|
+
for (const root of roots) {
|
|
212
|
+
if (p === root || p.startsWith(root.endsWith(sep) ? root : root + sep)) {
|
|
213
|
+
return `is inside agent-writable root ${root}`;
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
return null;
|
|
217
|
+
};
|
|
218
|
+
const hit = underRoots(raw);
|
|
219
|
+
if (hit)
|
|
220
|
+
return `cmd ${raw} ${hit}`;
|
|
221
|
+
const uid = typeof process.getuid === 'function' ? process.getuid() : null;
|
|
222
|
+
const checkParentChain = (p) => {
|
|
223
|
+
let dir = dirname(p);
|
|
224
|
+
for (;;) {
|
|
225
|
+
const parentHit = underRoots(dir);
|
|
226
|
+
if (parentHit)
|
|
227
|
+
return `parent dir ${dir} ${parentHit}`;
|
|
228
|
+
if (dir === dirname(dir))
|
|
229
|
+
return null;
|
|
230
|
+
let st;
|
|
231
|
+
try {
|
|
232
|
+
st = statSync(dir);
|
|
233
|
+
}
|
|
234
|
+
catch {
|
|
235
|
+
dir = dirname(dir);
|
|
236
|
+
continue;
|
|
237
|
+
}
|
|
238
|
+
const writable = (st.mode & 0o222) !== 0;
|
|
239
|
+
if (writable) {
|
|
240
|
+
if (uid !== null && st.uid === uid)
|
|
241
|
+
return `parent dir ${dir} is writable by the agent uid`;
|
|
242
|
+
if ((st.mode & 0o022) !== 0)
|
|
243
|
+
return `parent dir ${dir} is group/world-writable`;
|
|
244
|
+
}
|
|
245
|
+
dir = dirname(dir);
|
|
246
|
+
}
|
|
247
|
+
};
|
|
248
|
+
// 目标不存在(可后装):仅当父目录链不可换时放行;存在时连同 realpath 一并检查
|
|
249
|
+
let real = raw;
|
|
250
|
+
try {
|
|
251
|
+
real = realpathSync(raw);
|
|
252
|
+
const realHit = underRoots(real);
|
|
253
|
+
if (realHit)
|
|
254
|
+
return `cmd ${real} ${realHit} (symlink target)`;
|
|
255
|
+
}
|
|
256
|
+
catch {
|
|
257
|
+
const parent = checkParentChain(raw);
|
|
258
|
+
if (parent)
|
|
259
|
+
return `cmd ${raw}: ${parent}`;
|
|
260
|
+
return null;
|
|
261
|
+
}
|
|
262
|
+
const parent = checkParentChain(real) ?? checkParentChain(raw);
|
|
263
|
+
if (parent)
|
|
264
|
+
return `cmd ${raw}: ${parent}`;
|
|
265
|
+
// Windows 无 POSIX mode 语义(读回恒 0666):roots + 父目录链即全部口径(win32 边界)
|
|
266
|
+
if (process.platform === 'win32')
|
|
267
|
+
return null;
|
|
268
|
+
let st;
|
|
269
|
+
try {
|
|
270
|
+
st = statSync(real);
|
|
271
|
+
}
|
|
272
|
+
catch {
|
|
273
|
+
return `cmd ${real} unreadable`;
|
|
274
|
+
}
|
|
275
|
+
if ((st.mode & 0o222) === 0)
|
|
276
|
+
return null;
|
|
277
|
+
if (uid !== null && st.uid === uid)
|
|
278
|
+
return `cmd ${real} is writable by the agent uid (${uid}) — replaceable binary`;
|
|
279
|
+
if ((st.mode & 0o022) !== 0)
|
|
280
|
+
return `cmd ${real} is group/world-writable — replaceable binary`;
|
|
281
|
+
return null;
|
|
282
|
+
}
|
|
283
|
+
/**
|
|
284
|
+
* 提权可写根的统一口径(daemon 启动探测与 resolve 校验共用,防两处漂移)。
|
|
285
|
+
*
|
|
286
|
+
* @param options.workspaces - agent workspace 集合
|
|
287
|
+
* @param options.transactionRoots - 配置 transactionRoots
|
|
288
|
+
* @returns 可写根列表(含 home/tmp/OCTOPI_HOME)
|
|
289
|
+
*/
|
|
290
|
+
export function escalationWritableRoots(options) {
|
|
291
|
+
return [
|
|
292
|
+
...(options?.workspaces ?? []),
|
|
293
|
+
...(options?.transactionRoots ?? []),
|
|
294
|
+
homedir(),
|
|
295
|
+
tmpdir(),
|
|
296
|
+
resolve(homedir(), '.octopi'),
|
|
297
|
+
];
|
|
298
|
+
}
|
|
299
|
+
/**
|
|
300
|
+
* 启动期探测:声明了提权就必须真的拿得到(拍板 #5:拒绝启动,禁止降级静默)。
|
|
301
|
+
*
|
|
302
|
+
* @param config - 提权策略(配置形或 resolved 均可)
|
|
303
|
+
* @param options.writableRoots - TOCTOU 护栏的可写根集合
|
|
304
|
+
* @returns ok 或拒绝原因
|
|
305
|
+
*/
|
|
306
|
+
export async function probeEscalationReadiness(config, options) {
|
|
307
|
+
const escalation = {
|
|
308
|
+
policy: config?.policy ?? 'none',
|
|
309
|
+
via: config?.via ?? 'sudo',
|
|
310
|
+
allow: config?.allow ?? [],
|
|
311
|
+
};
|
|
312
|
+
if (escalation.policy === 'none')
|
|
313
|
+
return { ok: true };
|
|
314
|
+
if (escalation.policy === 'full') {
|
|
315
|
+
// 全量档(P4)没有 allowlist 面;带 allow 规则 = 配置死键(schema 已拒,库路径兜底)
|
|
316
|
+
if (escalation.allow.length > 0) {
|
|
317
|
+
return { ok: false, reason: 'escalation.policy=full takes no escalation.allow rules (exact-match list is an allowlist-only concept)' };
|
|
318
|
+
}
|
|
319
|
+
}
|
|
320
|
+
else if (escalation.allow.length === 0) {
|
|
321
|
+
return { ok: false, reason: 'escalation.policy=allowlist but effectPolicy.escalation.allow is empty' };
|
|
322
|
+
}
|
|
323
|
+
for (const rule of escalation.allow) {
|
|
324
|
+
const targets = escalationRuleTargets(rule, escalation.via);
|
|
325
|
+
if ('invalid' in targets)
|
|
326
|
+
return { ok: false, reason: `allowlist rule rejected: ${targets.invalid}` };
|
|
327
|
+
for (const target of targets.targets) {
|
|
328
|
+
const bad = checkEscalationBinary(target, options?.writableRoots ?? escalationWritableRoots());
|
|
329
|
+
if (bad)
|
|
330
|
+
return { ok: false, reason: `allowlist rule rejected: ${bad}` };
|
|
331
|
+
}
|
|
332
|
+
}
|
|
333
|
+
if (escalation.via === 'sudo') {
|
|
334
|
+
// 绝对路径执行(裸名 sudo 可被 PATH 劫持);探测≠规则被 sudoers 授权(文档如实声明)
|
|
335
|
+
const probe = await runPrivilegedExec({
|
|
336
|
+
cmd: '/usr/bin/sudo',
|
|
337
|
+
args: ['-n', 'true'],
|
|
338
|
+
via: 'sudo',
|
|
339
|
+
timeoutMs: 5000,
|
|
340
|
+
});
|
|
341
|
+
if (probe.exitCode !== 0) {
|
|
342
|
+
return {
|
|
343
|
+
ok: false,
|
|
344
|
+
reason: `escalation.via=sudo but ` + '`/usr/bin/sudo -n true`' + ` failed (exit=${probe.exitCode}): ${probe.stderr.trim()}`,
|
|
345
|
+
};
|
|
346
|
+
}
|
|
347
|
+
return { ok: true };
|
|
348
|
+
}
|
|
349
|
+
// via: direct —— 进程自身必须已高权限(POSIX euid 0 / win32 fsutil 探测)
|
|
350
|
+
if (process.platform === 'win32') {
|
|
351
|
+
const fsutil = `${process.env.SystemRoot ?? 'C:\\Windows'}\\System32\\fsutil.exe`;
|
|
352
|
+
const probe = await runPrivilegedExec({ cmd: fsutil, args: ['dirty', 'query', 'C:'], via: 'direct', timeoutMs: 5000 });
|
|
353
|
+
if (probe.exitCode !== 0) {
|
|
354
|
+
return { ok: false, reason: 'escalation.via=direct but process is not elevated (`fsutil dirty query` failed)' };
|
|
355
|
+
}
|
|
356
|
+
return { ok: true };
|
|
357
|
+
}
|
|
358
|
+
const euid = typeof process.geteuid === 'function' ? process.geteuid() : -1;
|
|
359
|
+
if (euid !== 0) {
|
|
360
|
+
return { ok: false, reason: `escalation.via=direct but geteuid()=${euid} (need 0)` };
|
|
361
|
+
}
|
|
362
|
+
return { ok: true };
|
|
363
|
+
}
|
|
364
|
+
/**
|
|
365
|
+
* 本进程是否已高权限(root / Windows elevated 管理员令牌)。
|
|
366
|
+
*
|
|
367
|
+
* POSIX 同步读 `geteuid()`;win32 走 `fsutil dirty query` 行为探测(与
|
|
368
|
+
* `probeEscalationReadiness` 的 direct 分支同口径,不读配置位、不猜 token)。
|
|
369
|
+
* 结果按进程生命期缓存(权限不可自行提升,探测一次即事实不变)。
|
|
370
|
+
*
|
|
371
|
+
* @returns true = 高权限进程
|
|
372
|
+
*/
|
|
373
|
+
export async function isProcessElevated() {
|
|
374
|
+
if (cachedElevated !== undefined)
|
|
375
|
+
return cachedElevated;
|
|
376
|
+
if (process.platform === 'win32') {
|
|
377
|
+
const fsutil = `${process.env.SystemRoot ?? 'C:\\Windows'}\\System32\\fsutil.exe`;
|
|
378
|
+
const probe = await runPrivilegedExec({
|
|
379
|
+
cmd: fsutil,
|
|
380
|
+
args: ['dirty', 'query', 'C:'],
|
|
381
|
+
via: 'direct',
|
|
382
|
+
timeoutMs: 5000,
|
|
383
|
+
});
|
|
384
|
+
cachedElevated = probe.exitCode === 0;
|
|
385
|
+
}
|
|
386
|
+
else {
|
|
387
|
+
const euid = typeof process.geteuid === 'function' ? process.geteuid() : -1;
|
|
388
|
+
cachedElevated = euid === 0;
|
|
389
|
+
}
|
|
390
|
+
return cachedElevated;
|
|
391
|
+
}
|
|
392
|
+
let cachedElevated;
|
|
393
|
+
/** 同步口径的高权限猜测(POSIX 可判;win32 同步不可判时如实返回 false 交由异步探测补) */
|
|
394
|
+
export function isProcessElevatedSync() {
|
|
395
|
+
if (process.platform === 'win32')
|
|
396
|
+
return false;
|
|
397
|
+
return typeof process.geteuid === 'function' ? process.geteuid() === 0 : false;
|
|
398
|
+
}
|
|
399
|
+
/**
|
|
400
|
+
* root/elevated 部署的显式 privileged 声明断言(§5 P4 root 部署语义)。
|
|
401
|
+
*
|
|
402
|
+
* daemon 以 root 跑时没有 sudo,危险轴变成「笼不笼 × uid=0」——启动期高权限进程
|
|
403
|
+
* 必须在 effectPolicy 里显式 `privilegedAck` 表态,拿不到声明就拒绝启动,
|
|
404
|
+
* 不允许「root 就这么跑着」的静默特权态。
|
|
405
|
+
*
|
|
406
|
+
* @param params.elevated - 进程是否高权限(`isProcessElevated` 探测值)
|
|
407
|
+
* @param params.privilegedAck - effectPolicy.privilegedAck(可缺省)
|
|
408
|
+
* @param params.scope - 出错信息里的配置面标识(如 `<top>` / agent id)
|
|
409
|
+
* @throws `privileged_declaration_required`(elevated 且无声明)
|
|
410
|
+
*/
|
|
411
|
+
export function assertPrivilegedDeclaration(params) {
|
|
412
|
+
if (!params.elevated)
|
|
413
|
+
return;
|
|
414
|
+
if (params.privilegedAck?.trim())
|
|
415
|
+
return;
|
|
416
|
+
throw new Error(`privileged_declaration_required (${params.scope}): process is elevated (root/admin) but ` +
|
|
417
|
+
`effectPolicy.privilegedAck is missing — declare the privileged deployment explicitly or run unprivileged`);
|
|
418
|
+
}
|
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 进程只读诊断原语(ops P1,零权限放松)
|
|
3
|
+
*
|
|
4
|
+
* 引擎侧实现,**不经 shell 工具 / ProcessSandbox**:
|
|
5
|
+
* - macOS 牢笼拒 exec setuid 的 `ps`(OS 不变量),笼内 shell 拿不到进程表;
|
|
6
|
+
* - Linux bwrap 自带新 pidns,笼内 shell 物理看不到宿主进程。
|
|
7
|
+
* 因此「看进程」只能由引擎进程自己(牢笼外)读 procfs / 调 `ps`。
|
|
8
|
+
* 契约见 `arch/ops-privileged-mode.md` §5 P1。只读:不杀进程、不改任何状态。
|
|
9
|
+
*
|
|
10
|
+
* 所有 spawn 走异步 `execFile`(对齐 runGit 惯例):daemon 单线程,同步 spawn
|
|
11
|
+
* 会在 ps/powershell 挂起的最坏情形冻结 gateway 与全部并发 session。
|
|
12
|
+
*/
|
|
13
|
+
/** 单个进程的只读快照 */
|
|
14
|
+
export interface ProcessInfoEntry {
|
|
15
|
+
pid: number;
|
|
16
|
+
/** 父 pid;来源给不出时为 null(如实反映,不猜) */
|
|
17
|
+
ppid: number | null;
|
|
18
|
+
/** 完整命令行(argv 空格连接);给不出时退化为可执行名 */
|
|
19
|
+
command: string | null;
|
|
20
|
+
rssBytes: number | null;
|
|
21
|
+
/**
|
|
22
|
+
* 累计 CPU 时间(user+sys,毫秒)。
|
|
23
|
+
* CPU 占用率需要采样语义,不混进本字段(一个字段一个含义)。
|
|
24
|
+
*/
|
|
25
|
+
cpuTimeMs: number | null;
|
|
26
|
+
threads: number | null;
|
|
27
|
+
}
|
|
28
|
+
/** 一次枚举的结果(含来源与诚实降级) */
|
|
29
|
+
export interface ProcessListResult {
|
|
30
|
+
processes: ProcessInfoEntry[];
|
|
31
|
+
source: 'procfs' | 'ps' | 'powershell';
|
|
32
|
+
/** false = 来源整体取不到/明显不全(降级),不等于「成功但没有进程」 */
|
|
33
|
+
complete: boolean;
|
|
34
|
+
notes: string[];
|
|
35
|
+
}
|
|
36
|
+
/** 枚举选项(全部如实生效,不静默忽略) */
|
|
37
|
+
export interface ListProcessesOptions {
|
|
38
|
+
/** 只保留这些 pid(扫描仍按来源读取,过滤在内存完成) */
|
|
39
|
+
pids?: number[];
|
|
40
|
+
/** 命令行子串过滤(ASCII 大小写不敏感) */
|
|
41
|
+
nameContains?: string;
|
|
42
|
+
/** 排序键:`pid` 升序 / `rss` 降序(并列按 pid 升序) */
|
|
43
|
+
sort?: 'pid' | 'rss';
|
|
44
|
+
/** 截断上限;被截断时 `truncated` 为 true */
|
|
45
|
+
limit?: number;
|
|
46
|
+
}
|
|
47
|
+
/** 过滤/排序/截断的结果 */
|
|
48
|
+
export interface SelectedProcesses {
|
|
49
|
+
selected: ProcessInfoEntry[];
|
|
50
|
+
/** 过滤前条目数 */
|
|
51
|
+
total: number;
|
|
52
|
+
/** 过滤后、截断前条目数(与 `total` 并列,避免「被过滤」误读成「被吞」) */
|
|
53
|
+
matched: number;
|
|
54
|
+
truncated: boolean;
|
|
55
|
+
}
|
|
56
|
+
/** 祖先链查找结果 */
|
|
57
|
+
export interface AncestorChain {
|
|
58
|
+
/** 从最远已知祖先到 `pid` 自身(含);链尾恒为 `pid` */
|
|
59
|
+
chain: number[];
|
|
60
|
+
/** false = 中间有断链(来源缺 pid/ppid),链不完整 */
|
|
61
|
+
complete: boolean;
|
|
62
|
+
notes: string[];
|
|
63
|
+
}
|
|
64
|
+
/** 表解析结果:条目 + 被跳过的非空行数(诚实记账,禁止静默丢行) */
|
|
65
|
+
export interface TableParseResult {
|
|
66
|
+
entries: ProcessInfoEntry[];
|
|
67
|
+
/** 非空但不可解析的行数(warning / 截断 / 列错位);>0 = 来源不全 */
|
|
68
|
+
skipped: number;
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* Pick the executable image out of `lsof -a -d txt -Fn` output.
|
|
72
|
+
*
|
|
73
|
+
* lsof prints one `n<name>` line per matching descriptor, in descriptor order.
|
|
74
|
+
* The first `txt` entry is the executable itself; every later one is a
|
|
75
|
+
* dyld/mmap'd library (`/usr/lib/dyld`, framework dylibs). Taking "the first n
|
|
76
|
+
* line" is therefore the executable, not "any n line".
|
|
77
|
+
*
|
|
78
|
+
* @param output - raw stdout of `lsof -p <pid> -a -d txt -Fn`
|
|
79
|
+
* @returns absolute executable path, or null when the output carries none
|
|
80
|
+
*/
|
|
81
|
+
export declare function firstExecutableFromLsof(output: string): string | null;
|
|
82
|
+
/**
|
|
83
|
+
* Parse `ps` table output (`-o pid=,ppid=,rss=,time=,[thcount=,]command=`).
|
|
84
|
+
*
|
|
85
|
+
* `command` is the remainder of the line after the numeric columns, so argv
|
|
86
|
+
* spacing inside it is preserved verbatim. Lines that do not parse are counted
|
|
87
|
+
* in `skipped` (never dropped silently): a warning line and a corrupted data
|
|
88
|
+
* line look the same to a regex, so any skip degrades `complete` upstream.
|
|
89
|
+
*
|
|
90
|
+
* @param output - raw stdout of the ps invocation
|
|
91
|
+
* @param includeThreads - whether the table carried a `thcount` column
|
|
92
|
+
* @returns parsed entries plus the count of skipped non-empty lines
|
|
93
|
+
*/
|
|
94
|
+
export declare function parsePsProcessTable(output: string, includeThreads: boolean): TableParseResult;
|
|
95
|
+
/**
|
|
96
|
+
* Parse a ps `time` cell (`[[dd-]hh:]mm:ss[.fraction]`, cumulative CPU).
|
|
97
|
+
*
|
|
98
|
+
* @param text - the raw cell
|
|
99
|
+
* @returns cumulative CPU milliseconds, or null when the cell is unparseable
|
|
100
|
+
*/
|
|
101
|
+
export declare function parseCpuTimeToMs(text: string): number | null;
|
|
102
|
+
/**
|
|
103
|
+
* Assemble one entry from `/proc/<pid>` file contents (pure; procfs I/O stays
|
|
104
|
+
* in {@link listProcesses}).
|
|
105
|
+
*
|
|
106
|
+
* `stat` comm may contain spaces and parentheses, so it is taken between the
|
|
107
|
+
* first `(` and the **last** `)` — never by splitting on whitespace. ppid comes
|
|
108
|
+
* from `stat` field 4; `threads` deliberately comes from `status:Threads`
|
|
109
|
+
* instead of `stat` field 20 (one less positional index to get wrong).
|
|
110
|
+
*
|
|
111
|
+
* @param pid - the pid these contents came from
|
|
112
|
+
* @param stat - `/proc/<pid>/stat`
|
|
113
|
+
* @param status - `/proc/<pid>/status`
|
|
114
|
+
* @param cmdline - `/proc/<pid>/cmdline` (NUL-separated argv; empty for kernel threads)
|
|
115
|
+
* @returns parsed entry
|
|
116
|
+
*/
|
|
117
|
+
export declare function parseProcPidEntry(pid: number, stat: string, status: string, cmdline: Buffer | string): ProcessInfoEntry;
|
|
118
|
+
/**
|
|
119
|
+
* Parse the tab-separated `Get-CimInstance Win32_Process` table produced by
|
|
120
|
+
* {@link listProcesses} on win32.
|
|
121
|
+
*
|
|
122
|
+
* Columns: pid, ppid, workingSet, kernelModeTime, userModeTime (100ns units),
|
|
123
|
+
* threadCount, command. A command containing tabs keeps them (join back).
|
|
124
|
+
* Unparseable lines are counted in `skipped`, never dropped silently.
|
|
125
|
+
*
|
|
126
|
+
* @param output - raw powershell stdout
|
|
127
|
+
* @returns parsed entries plus the count of skipped non-empty lines
|
|
128
|
+
*/
|
|
129
|
+
export declare function parsePowerShellProcessTable(output: string): TableParseResult;
|
|
130
|
+
/**
|
|
131
|
+
* Walk the ppid map from `pid` up to the topmost reachable ancestor (pure).
|
|
132
|
+
*
|
|
133
|
+
* @param ppidByPid - pid → parent pid (null = source reported unknown)
|
|
134
|
+
* @param pid - starting pid (always included as the chain tail)
|
|
135
|
+
* @returns chain (topmost ancestor first, `pid` last) and whether every link resolved
|
|
136
|
+
*/
|
|
137
|
+
export declare function buildAncestorChain(ppidByPid: ReadonlyMap<number, number | null>, pid: number): {
|
|
138
|
+
chain: number[];
|
|
139
|
+
complete: boolean;
|
|
140
|
+
};
|
|
141
|
+
/**
|
|
142
|
+
* Apply filters, sort and limit to an enumeration (pure; all options honored).
|
|
143
|
+
*
|
|
144
|
+
* @param processes - enumerated entries
|
|
145
|
+
* @param options - filter/sort/limit options
|
|
146
|
+
* @returns selection with totals (`total` = pre-filter, `matched` = post-filter)
|
|
147
|
+
*/
|
|
148
|
+
export declare function selectProcesses(processes: readonly ProcessInfoEntry[], options?: ListProcessesOptions): SelectedProcesses;
|
|
149
|
+
/**
|
|
150
|
+
* Enumerate running processes (read-only, engine-side).
|
|
151
|
+
*
|
|
152
|
+
* Sources: Linux `/proc` (works on slim images without `ps`), other POSIX `ps`,
|
|
153
|
+
* win32 `Get-CimInstance`. A source that cannot be read at all degrades
|
|
154
|
+
* honestly (`complete: false` + notes) — never an empty success.
|
|
155
|
+
*
|
|
156
|
+
* @returns the enumeration with its source and degradation notes
|
|
157
|
+
*/
|
|
158
|
+
export declare function listProcesses(): Promise<ProcessListResult>;
|
|
159
|
+
/**
|
|
160
|
+
* Find the ancestor chain of a pid (read-only).
|
|
161
|
+
*
|
|
162
|
+
* `process.ppid` is seeded for the caller's own pid so a degraded listing still
|
|
163
|
+
* yields the one link Node already knows.
|
|
164
|
+
*
|
|
165
|
+
* @param pid - target pid
|
|
166
|
+
* @param listed - a fresh enumeration to walk (reuse to avoid a second scan)
|
|
167
|
+
* @returns chain (topmost first, `pid` last) with completeness and source notes
|
|
168
|
+
*/
|
|
169
|
+
export declare function getAncestorPidChain(pid: number, listed?: ProcessListResult): Promise<AncestorChain>;
|
|
170
|
+
/**
|
|
171
|
+
* Resolve the executable image of a pid (read-only, best-effort).
|
|
172
|
+
*
|
|
173
|
+
* linux: `/proc/<pid>/exe` readlink (then `ps -o comm=`); darwin: `lsof` txt
|
|
174
|
+
* (then `ps`; lsof is not setuid so it also works inside the Seatbelt jail);
|
|
175
|
+
* win32: `tasklist` name (no path without elevation).
|
|
176
|
+
*
|
|
177
|
+
* @param pid - target pid
|
|
178
|
+
* @returns image path (or bare name where paths are unavailable), null when unresolvable
|
|
179
|
+
*/
|
|
180
|
+
export declare function resolveProcessImage(pid: number): Promise<string | null>;
|