@octopi-agent/engine 0.86.38 → 0.90.11

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.
Files changed (83) hide show
  1. package/dist/config-schema/agent.js +12 -5
  2. package/dist/config-schema/context.d.ts +1 -1
  3. package/dist/config-schema/engine.d.ts +4 -4
  4. package/dist/config-schema/governance.js +3 -2
  5. package/dist/config-schema/models.d.ts +2 -2
  6. package/dist/config-schema/shared.d.ts +3 -0
  7. package/dist/config-schema/shared.js +12 -0
  8. package/dist/config-schema/substrate.d.ts +1 -1
  9. package/dist/config.d.ts +31 -9
  10. package/dist/config.js +66 -74
  11. package/dist/harness/agent/builder.d.ts +3 -2
  12. package/dist/harness/agent/builder.js +11 -7
  13. package/dist/harness/agent/config-bridge.js +4 -1
  14. package/dist/harness/agent/tool-purpose.d.ts +9 -1
  15. package/dist/harness/agent/tool-purpose.js +11 -2
  16. package/dist/harness/agent/wire-agent-builder.js +9 -2
  17. package/dist/harness/collaboration/autonomous-subsystem/boundary/validator.d.ts +11 -1
  18. package/dist/harness/collaboration/autonomous-subsystem/boundary/validator.js +11 -1
  19. package/dist/harness/collaboration/autonomous-subsystem/loader.d.ts +13 -0
  20. package/dist/harness/collaboration/autonomous-subsystem/loader.js +16 -1
  21. package/dist/harness/collaboration/autonomous-subsystem/runtime.d.ts +4 -0
  22. package/dist/harness/collaboration/autonomous-subsystem/runtime.js +3 -1
  23. package/dist/harness/context/default-context-engine.js +4 -4
  24. package/dist/harness/context/layer-types.d.ts +36 -0
  25. package/dist/harness/context/layer-types.js +38 -0
  26. package/dist/harness/context/root-instructions.js +1 -1
  27. package/dist/harness/context/system-prompt-assembler.js +10 -4
  28. package/dist/harness/context/tool-result-aging.js +2 -2
  29. package/dist/harness/context/turn-envelope.d.ts +1 -1
  30. package/dist/harness/context/turn-envelope.js +1 -1
  31. package/dist/harness/extension/execution-environment/effect-policy.d.ts +11 -1
  32. package/dist/harness/extension/execution-environment/effect-policy.js +24 -0
  33. package/dist/harness/extension/execution-environment/index.d.ts +1 -1
  34. package/dist/harness/extension/execution-environment/index.js +1 -1
  35. package/dist/harness/extension/execution-environment/isolation.js +5 -1
  36. package/dist/harness/extension/execution-environment/sandbox.js +36 -8
  37. package/dist/harness/extension/plugin-ecosystem/tools/allowlisted-run.d.ts +6 -0
  38. package/dist/harness/extension/plugin-ecosystem/tools/allowlisted-run.js +17 -0
  39. package/dist/harness/extension/plugin-ecosystem/tools/file-search.js +10 -17
  40. package/dist/harness/extension/plugin-ecosystem/tools/git-runner.d.ts +31 -0
  41. package/dist/harness/extension/plugin-ecosystem/tools/git-runner.js +104 -0
  42. package/dist/harness/extension/plugin-ecosystem/tools/git-status-snapshot.d.ts +111 -0
  43. package/dist/harness/extension/plugin-ecosystem/tools/git-status-snapshot.js +197 -0
  44. package/dist/harness/extension/plugin-ecosystem/tools/git-tools.d.ts +8 -8
  45. package/dist/harness/extension/plugin-ecosystem/tools/git-tools.js +9 -100
  46. package/dist/harness/extension/plugin-ecosystem/tools/index.d.ts +4 -0
  47. package/dist/harness/extension/plugin-ecosystem/tools/index.js +2 -0
  48. package/dist/harness/index.d.ts +2 -0
  49. package/dist/harness/index.js +1 -0
  50. package/dist/harness/knowledge/file-identity.d.ts +8 -0
  51. package/dist/harness/knowledge/file-identity.js +26 -1
  52. package/dist/harness/knowledge/grounding.js +5 -5
  53. package/dist/harness/knowledge/index-store.d.ts +31 -4
  54. package/dist/harness/knowledge/index-store.js +121 -39
  55. package/dist/harness/knowledge/ingest.d.ts +115 -115
  56. package/dist/harness/knowledge/ingest.js +150 -150
  57. package/dist/harness/knowledge/knowledge-serve-child.js +1 -1
  58. package/dist/harness/knowledge/purge.js +4 -1
  59. package/dist/harness/memory/backfill-coverage.js +3 -1
  60. package/dist/harness/observability/observer/hub.js +30 -1
  61. package/dist/harness/observability/observer/types.d.ts +23 -0
  62. package/dist/harness/run/runner.d.ts +16 -0
  63. package/dist/harness/run/runner.js +139 -26
  64. package/dist/harness/session/history/port.js +15 -5
  65. package/dist/harness/session/in-memory-store.d.ts +5 -0
  66. package/dist/harness/session/in-memory-store.js +33 -2
  67. package/dist/harness/session/title.js +25 -9
  68. package/dist/harness/shared/events/agent-event-map.d.ts +26 -0
  69. package/dist/harness/shared/events/agent-event-map.js +2 -0
  70. package/dist/index.d.ts +4 -2
  71. package/dist/index.js +3 -2
  72. package/dist/integration/observability/run-telemetry.d.ts +8 -0
  73. package/dist/integration/observability/run-telemetry.js +31 -8
  74. package/dist/integration/observability/trace-collector.js +26 -4
  75. package/dist/integration/observability/trace-events.d.ts +1 -0
  76. package/dist/integration/observability/trace-events.js +2 -0
  77. package/dist/integration/observability/trace-logger.js +27 -17
  78. package/dist/integration/storage/jsonl.d.ts +19 -1
  79. package/dist/integration/storage/jsonl.js +96 -3
  80. package/dist/paths.d.ts +19 -0
  81. package/dist/paths.js +38 -1
  82. package/dist/subsystems/safety-guard/config.yaml +3 -1
  83. package/package.json +2 -2
@@ -1,10 +1,16 @@
1
1
  import type { SubsystemSpec } from './types.js';
2
+ import { type SecurityEnforcementContext } from './boundary/validator.js';
2
3
  export interface SubsystemLoaderConfig {
3
4
  builtinDir?: string;
4
5
  userDir?: string;
5
6
  projectDir?: string;
6
7
  /** node_modules 目录(用于 npm 子系统发现) */
7
8
  npmDir?: string;
9
+ /**
10
+ * SEC-6 能力注入(测试/确定性场景)。缺省实测环境:
11
+ * `probeProcessIsolation()` + L4 process 最低线评估。
12
+ */
13
+ securityEnforcement?: SecurityEnforcementContext;
8
14
  }
9
15
  export interface LoadResult {
10
16
  specs: SubsystemSpec[];
@@ -18,7 +24,14 @@ export declare class SubsystemLoader {
18
24
  private userDir?;
19
25
  private projectDir?;
20
26
  private npmDir?;
27
+ private securityEnforcement?;
21
28
  constructor(config: SubsystemLoaderConfig);
29
+ /**
30
+ * SEC-6 能力解析:注入优先;缺省实测环境(L4 process 最低线评估)。
31
+ *
32
+ * @returns 宿主能力声明
33
+ */
34
+ private resolveSecurityEnforcement;
22
35
  loadAll(): Promise<LoadResult>;
23
36
  /**
24
37
  * 加载一级目录:单 spec 包,或多 spec 包(子目录含 config/SUBSYSTEM.md + shared 静默跳过)
@@ -2,6 +2,7 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs';
2
2
  import { basename, join } from 'node:path';
3
3
  import { createRequire } from 'node:module';
4
4
  import { validateSubsystemSpec } from './boundary/validator.js';
5
+ import { probeProcessIsolation, assessL4ProcessMinimum } from '../../extension/execution-environment/process-isolation.js';
5
6
  // js-yaml 自身未附带 d.ts;仅使用 load,避免为类型强装 @types(与当前 TS 版本 peer 冲突)
6
7
  // 惰性 require:包缺失时只在真正解析 YAML 时失败,不阻断模块 import
7
8
  let loadYamlFn;
@@ -17,11 +18,24 @@ export class SubsystemLoader {
17
18
  userDir;
18
19
  projectDir;
19
20
  npmDir;
21
+ securityEnforcement;
20
22
  constructor(config) {
21
23
  this.builtinDir = config.builtinDir;
22
24
  this.userDir = config.userDir;
23
25
  this.projectDir = config.projectDir;
24
26
  this.npmDir = config.npmDir;
27
+ this.securityEnforcement = config.securityEnforcement;
28
+ }
29
+ /**
30
+ * SEC-6 能力解析:注入优先;缺省实测环境(L4 process 最低线评估)。
31
+ *
32
+ * @returns 宿主能力声明
33
+ */
34
+ async resolveSecurityEnforcement() {
35
+ if (this.securityEnforcement)
36
+ return this.securityEnforcement;
37
+ const profile = await probeProcessIsolation();
38
+ return { l4Available: assessL4ProcessMinimum(profile).ok };
25
39
  }
26
40
  async loadAll() {
27
41
  const specs = new Map();
@@ -188,7 +202,8 @@ export class SubsystemLoader {
188
202
  if (missingExplicitFields.length > 0) {
189
203
  return { error: `Missing required explicit fields: ${missingExplicitFields.join(', ')}` };
190
204
  }
191
- const errors = validateSubsystemSpec(spec);
205
+ const enforcement = await this.resolveSecurityEnforcement();
206
+ const errors = validateSubsystemSpec(spec, enforcement);
192
207
  if (errors.length > 0) {
193
208
  return { error: `Validation failed: ${errors.map((e) => `${e.field}: ${e.message}`).join('; ')}` };
194
209
  }
@@ -14,6 +14,7 @@ import type { SubsystemSpec, AgentContext, SenseContext } from './types.js';
14
14
  import { MetricsStore } from './sense/metrics.js';
15
15
  import type { ModelLevelMap } from './types.js';
16
16
  import { SignalBus } from './signal/bus.js';
17
+ import { type SecurityEnforcementContext } from './boundary/validator.js';
17
18
  /** 子系统运行终态(与 SubsystemRun.status 对齐) */
18
19
  export type SubsystemRunStatus = 'success' | 'failed' | 'timeout' | 'degraded';
19
20
  /**
@@ -44,9 +45,12 @@ export interface SubsystemRuntimeConfig {
44
45
  deps: SharedDeps;
45
46
  auditDir?: string;
46
47
  agentId?: string;
48
+ /** SEC-6 宿主能力声明(必填):`sandboxed` 声明只有在 L4 可用时才放行 */
49
+ securityEnforcement: SecurityEnforcementContext;
47
50
  }
48
51
  export declare class SubsystemRuntime {
49
52
  private deps;
53
+ private securityEnforcement;
50
54
  private senseEngine;
51
55
  private thinkExecutor;
52
56
  private signalBus;
@@ -23,6 +23,7 @@ import { buildAgentInput } from './sense/input-builder.js';
23
23
  // ── SubsystemRuntime ──
24
24
  export class SubsystemRuntime {
25
25
  deps;
26
+ securityEnforcement;
26
27
  senseEngine;
27
28
  thinkExecutor;
28
29
  signalBus;
@@ -37,6 +38,7 @@ export class SubsystemRuntime {
37
38
  activeTimeouts = new Map();
38
39
  constructor(config) {
39
40
  this.deps = config.deps;
41
+ this.securityEnforcement = config.securityEnforcement;
40
42
  this.senseEngine = new SenseEngine({
41
43
  events: config.deps.events,
42
44
  });
@@ -141,7 +143,7 @@ export class SubsystemRuntime {
141
143
  */
142
144
  register(spec) {
143
145
  // 校验
144
- const errors = validateSubsystemSpec(spec);
146
+ const errors = validateSubsystemSpec(spec, this.securityEnforcement);
145
147
  if (errors.length > 0) {
146
148
  return errors.map((e) => `[${e.field}] ${e.message}`);
147
149
  }
@@ -24,7 +24,7 @@ import { HybridCompressor } from './hybrid-compressor.js';
24
24
  import { DefaultBudgetAllocator } from './budget-allocator.js';
25
25
  import { SmartRouter } from './smart-router.js';
26
26
  import { compactStateKey } from './compact-key.js';
27
- import { isEngineCarrierSource } from './layer-types.js';
27
+ import { isTurnAnchor } from './layer-types.js';
28
28
  import { extractUserMessageText, isTurnStartContent, } from './turn-envelope.js';
29
29
  import { createCompactEngine } from './capabilities/compact/index.js';
30
30
  // ── 引擎实现 ──
@@ -1125,11 +1125,11 @@ export function isMidTurn(messages) {
1125
1125
  let lastGenuineUserIdx = -1;
1126
1126
  for (let i = 0; i < messages.length; i++) {
1127
1127
  const msg = messages[i];
1128
- if (msg.role !== 'user')
1129
- continue;
1128
+ // 「真实 user」收紧:agentId 归因的 user(appendCommandDiscourse)不重置边界,
1129
+ // 载体过滤走唯一谓词 isTurnAnchor
1130
1130
  if (msg.agentId)
1131
1131
  continue;
1132
- if (isEngineCarrierSource(msg.metadata?.source))
1132
+ if (!isTurnAnchor(msg))
1133
1133
  continue;
1134
1134
  lastGenuineUserIdx = i;
1135
1135
  }
@@ -204,6 +204,42 @@ export interface ContextAssembleParams {
204
204
  * @returns true 表示机器插槽(快照/grounding/附件/摘要)
205
205
  */
206
206
  export declare function isEngineCarrierSource(source: unknown): boolean;
207
+ /**
208
+ * 轮次锚点判定(turn 边界类消费方:isMidTurn / compact / tool-result-aging)。
209
+ *
210
+ * 能开轮的输入 = 真实用户发言 + `source:'runtime'` 的 activation 唤醒输入
211
+ * (compiler 打标、确实开轮且是该 turn 的输入);引擎载体插槽与 schedule
212
+ * notify 便签(`delivery:'notify'`)不开轮。2026-10-24 拍板拆分:wake
213
+ * 「开轮但不是人话」——两类消费方各取所需,一个布尔不再混答两个问题。
214
+ *
215
+ * @param msg - 消息(结构化入参,接受 Message 及其裁剪形态)
216
+ * @returns true = 该消息能作为 turn 边界锚点
217
+ */
218
+ export declare function isTurnAnchor(msg: {
219
+ role?: string;
220
+ metadata?: {
221
+ source?: unknown;
222
+ delivery?: unknown;
223
+ };
224
+ }): boolean;
225
+ /**
226
+ * 人话判定(人类文本类消费方:title / grounding.latestUserText / backfill userTurns)。
227
+ *
228
+ * 只有真实用户创作的文本才是「人话」:引擎载体插槽、schedule notify 便签、
229
+ * `source:'runtime'` 的 activation 唤醒输入(机器提示词)都会污染标题与 grounding 锚点。
230
+ * 注意本谓词**不看 agentId**:isMidTurn 另有「无 agentId 归因」的收紧
231
+ * (多 agent 共线语义),在其调用处叠加。
232
+ *
233
+ * @param msg - 消息(结构化入参,接受 Message 及其裁剪形态)
234
+ * @returns true = 真实用户创作的发言
235
+ */
236
+ export declare function isHumanSpeech(msg: {
237
+ role?: string;
238
+ metadata?: {
239
+ source?: unknown;
240
+ delivery?: unknown;
241
+ };
242
+ }): boolean;
207
243
  /**
208
244
  * 聊天回放隐藏谓词(D9 收敛的唯一真源)。
209
245
  *
@@ -90,6 +90,44 @@ const ENGINE_CARRIER_SOURCES = new Set([
90
90
  export function isEngineCarrierSource(source) {
91
91
  return ENGINE_CARRIER_SOURCES.has(source);
92
92
  }
93
+ /**
94
+ * 轮次锚点判定(turn 边界类消费方:isMidTurn / compact / tool-result-aging)。
95
+ *
96
+ * 能开轮的输入 = 真实用户发言 + `source:'runtime'` 的 activation 唤醒输入
97
+ * (compiler 打标、确实开轮且是该 turn 的输入);引擎载体插槽与 schedule
98
+ * notify 便签(`delivery:'notify'`)不开轮。2026-10-24 拍板拆分:wake
99
+ * 「开轮但不是人话」——两类消费方各取所需,一个布尔不再混答两个问题。
100
+ *
101
+ * @param msg - 消息(结构化入参,接受 Message 及其裁剪形态)
102
+ * @returns true = 该消息能作为 turn 边界锚点
103
+ */
104
+ export function isTurnAnchor(msg) {
105
+ if (msg.role !== 'user')
106
+ return false;
107
+ if (isEngineCarrierSource(msg.metadata?.source))
108
+ return false;
109
+ // schedule notify 是机器便签(producer 见 gateway setNotify),不是用户输入
110
+ if (msg.metadata?.delivery === 'notify')
111
+ return false;
112
+ return true;
113
+ }
114
+ /**
115
+ * 人话判定(人类文本类消费方:title / grounding.latestUserText / backfill userTurns)。
116
+ *
117
+ * 只有真实用户创作的文本才是「人话」:引擎载体插槽、schedule notify 便签、
118
+ * `source:'runtime'` 的 activation 唤醒输入(机器提示词)都会污染标题与 grounding 锚点。
119
+ * 注意本谓词**不看 agentId**:isMidTurn 另有「无 agentId 归因」的收紧
120
+ * (多 agent 共线语义),在其调用处叠加。
121
+ *
122
+ * @param msg - 消息(结构化入参,接受 Message 及其裁剪形态)
123
+ * @returns true = 真实用户创作的发言
124
+ */
125
+ export function isHumanSpeech(msg) {
126
+ if (!isTurnAnchor(msg))
127
+ return false;
128
+ // wake 是机器开轮输入:能锚定 turn,但不是人话
129
+ return msg.metadata?.source !== 'runtime';
130
+ }
93
131
  /**
94
132
  * 聊天回放隐藏谓词(D9 收敛的唯一真源)。
95
133
  *
@@ -60,7 +60,7 @@ function neutralizeClosingTags(text) {
60
60
  */
61
61
  function truncateToBytes(text, maxBytes) {
62
62
  let out = Buffer.from(text, 'utf-8').subarray(0, maxBytes).toString('utf-8');
63
- out = out.replace(/�+$/, '').replace(/\r?\n[^\n]*$/, '');
63
+ out = out.replace(/\uFFFD+$/, '').replace(/\r?\n[^\n]*$/, '');
64
64
  return out;
65
65
  }
66
66
  /**
@@ -7,6 +7,7 @@ import { DefaultContextAssembler } from './assembler.js';
7
7
  import { CognitionLayer, KnowledgeLayer, MemoryLayer, PersonaLayer, RuntimeLayer, SkillLayer, WisdomLayer, } from './layers.js';
8
8
  import { extractLayerQuery } from './layer-types.js';
9
9
  import { loadConstitution } from './constitution/load-constitution.js';
10
+ import { TOOL_PURPOSE_SYSTEM_NOTE } from '../agent/tool-purpose.js';
10
11
  const DEFAULT_SYSTEM_BUDGET_RATIO = 0.22;
11
12
  /**
12
13
  * Turn 信封阅读规则(缓存稳定固定块;永远拼进 system)。
@@ -24,9 +25,14 @@ export const TURN_SEMANTICS_MD = `## Turns (authoritative)
24
25
  - Never edit or delete \`<turn_start>\` / \`<turn_end>\` / past tool results.
25
26
  - If a tool needs old ephemeral detail, re-read the source (session log / files);
26
27
  do not assume old picks are still true.`;
27
- function withTurnRules(systemPrompt) {
28
+ /**
29
+ * 缓存稳定固定块(永远拼进 system):Turn 信封阅读规则置首,purpose 全局说明随后。
30
+ * purpose 详版+示例在此只写一次(方案 S)——schema 侧只留 TOOL_PURPOSE_PARAM 极短 stub。
31
+ */
32
+ function withFixedProtocolBlocks(systemPrompt) {
28
33
  const body = systemPrompt.trim();
29
- return body ? `${TURN_SEMANTICS_MD}\n\n---\n\n${body}` : TURN_SEMANTICS_MD;
34
+ const head = `${TURN_SEMANTICS_MD}\n\n---\n\n${TOOL_PURPOSE_SYSTEM_NOTE}`;
35
+ return body ? `${head}\n\n---\n\n${body}` : head;
30
36
  }
31
37
  export function createDefaultSystemPromptAssembler(options) {
32
38
  let preamble = options?.constitutionText ?? '';
@@ -79,7 +85,7 @@ export function createDefaultSystemPromptAssembler(options) {
79
85
  cognitionStore);
80
86
  const hasPreamble = Boolean(resolvedPreamble.trim());
81
87
  if (!hasPersona && !hasInjected && !hasSkill && !hasRetrieval && !hasPreamble) {
82
- return { systemPrompt: withTurnRules('') };
88
+ return { systemPrompt: withFixedProtocolBlocks('') };
83
89
  }
84
90
  // contextWindow 未知且未配置 systemBudgetTokens:
85
91
  // **跳过按窗口比例的预算**,但仍装配层(不按 token 硬裁,保留完整层内容)
@@ -185,7 +191,7 @@ export function createDefaultSystemPromptAssembler(options) {
185
191
  };
186
192
  }
187
193
  return {
188
- systemPrompt: withTurnRules(result.systemPrompt),
194
+ systemPrompt: withFixedProtocolBlocks(result.systemPrompt),
189
195
  runtimeSnapshot,
190
196
  manifest,
191
197
  skippedBudget,
@@ -22,7 +22,7 @@
22
22
  *
23
23
  * @module harness/context/tool-result-aging
24
24
  */
25
- import { isEngineCarrierSource } from './layer-types.js';
25
+ import { isTurnAnchor } from './layer-types.js';
26
26
  import { toolResultBody } from './tool-result-body.js';
27
27
  /** args / result 轮廓占 maxPointerChars 的比例(合计 ~0.65,加固定骨架 ≈ 目标) */
28
28
  const ARGS_OUTLINE_RATIO = 0.2;
@@ -79,7 +79,7 @@ export function computeToolResultAgingPlan(messages, opts) {
79
79
  let lastGenuineUserIdx = -1;
80
80
  for (let i = 0; i < messages.length; i++) {
81
81
  const msg = messages[i];
82
- if (msg.role === 'user' && !isEngineCarrierSource(msg.metadata?.source)) {
82
+ if (isTurnAnchor(msg)) {
83
83
  lastGenuineUserIdx = i;
84
84
  }
85
85
  for (const tc of msg.toolCalls ?? []) {
@@ -54,7 +54,7 @@ export declare function stripTurnContextXml(content: string | Message['content']
54
54
  *
55
55
  * 判形锚定到**正文开头**(允许前导空白):真实信封由 formatTurnStartContent 定形、必然以开标签起头;
56
56
  * 正文中途引用标签字面量(讨论协议/贴日志/知识语料)不得命中——否则普通 user 发言会被
57
- * 写一次守卫误判「已定形」(NEXT-STEPS D7)。
57
+ * 写一次守卫误判「已定形」(arch/open-problems.md D7)。
58
58
  */
59
59
  export declare function isTurnStartContent(content: string | Message['content'] | undefined | null): boolean;
60
60
  /** 是否 turn_end 正文(同 isTurnStartContent:锚定正文开头,防止字面量误判) */
@@ -89,7 +89,7 @@ export function stripTurnContextXml(content) {
89
89
  *
90
90
  * 判形锚定到**正文开头**(允许前导空白):真实信封由 formatTurnStartContent 定形、必然以开标签起头;
91
91
  * 正文中途引用标签字面量(讨论协议/贴日志/知识语料)不得命中——否则普通 user 发言会被
92
- * 写一次守卫误判「已定形」(NEXT-STEPS D7)。
92
+ * 写一次守卫误判「已定形」(arch/open-problems.md D7)。
93
93
  */
94
94
  export function isTurnStartContent(content) {
95
95
  return /^\s*<turn_start[\s>]/.test(messageText(content));
@@ -82,7 +82,7 @@ export interface EffectPolicyConfig {
82
82
  * `degrade` 降 effectiveMode + toolSurface=reduced + securityDegraded。
83
83
  */
84
84
  untrustedAdmission?: UntrustedAdmission;
85
- /** 额外事务 root(绝对路径);并入 allowRoots */
85
+ /** 额外事务 root(绝对路径或 ~ 形态,入口 trim → expand);并入 allowRoots */
86
86
  transactionRoots?: string[];
87
87
  pathContainment?: PathContainment;
88
88
  shellEscape?: ShellEscapePolicy;
@@ -150,6 +150,16 @@ export interface EffectiveEffectPolicy {
150
150
  maxFileSize?: number;
151
151
  };
152
152
  }
153
+ /**
154
+ * Whether the resolved policy demands a process jail (untrusted that survived
155
+ * untrusted admission). Single predicate shared by the run path (runner) and
156
+ * host-side read surfaces (WebUI git status endpoint) so the isolation level
157
+ * never drifts between them.
158
+ *
159
+ * @param eff - resolved effective policy
160
+ * @returns true when untrusted was requested and remains effective
161
+ */
162
+ export declare function requiresJail(eff: EffectiveEffectPolicy): boolean;
153
163
  /**
154
164
  * 展开 effectPolicy 为有效策略
155
165
  *
@@ -5,6 +5,7 @@
5
5
  * 见 arch/tool-effect-policy.md §7。
6
6
  */
7
7
  import { isAbsolute, resolve } from 'node:path';
8
+ import { expandHomePath } from '../../../paths.js';
8
9
  import { deniesReducedSurface, resolveToolCapabilities, } from './tool-capabilities.js';
9
10
  import { assessL4ProcessMinimum, } from './process-isolation.js';
10
11
  import { resolveHitlDecision } from '../../governance/human-in-the-loop/decision-cache.js';
@@ -68,6 +69,18 @@ const MODE_DEFAULTS = {
68
69
  shellJournal: 'snapshot',
69
70
  },
70
71
  };
72
+ /**
73
+ * Whether the resolved policy demands a process jail (untrusted that survived
74
+ * untrusted admission). Single predicate shared by the run path (runner) and
75
+ * host-side read surfaces (WebUI git status endpoint) so the isolation level
76
+ * never drifts between them.
77
+ *
78
+ * @param eff - resolved effective policy
79
+ * @returns true when untrusted was requested and remains effective
80
+ */
81
+ export function requiresJail(eff) {
82
+ return eff.requestedMode === 'untrusted' && eff.mode === 'untrusted';
83
+ }
71
84
  /**
72
85
  * 展开 effectPolicy 为有效策略
73
86
  *
@@ -90,6 +103,17 @@ const MODE_DEFAULTS = {
90
103
  * @throws Error when untrusted is refused
91
104
  */
92
105
  export function resolveEffectiveEffectPolicy(config, baseWorkspace, isolation) {
106
+ // `~` 前缀收口展开(Windows/Linux/macOS 通用):下游 allowRoots / tool cwd 只见
107
+ // 绝对路径;配置层(ConfigPathSchema)已先拒相对路径。顺序固定「trim → expand」,
108
+ // 库调用面传入带空白的 ` ~/x` 同样归一。
109
+ config = {
110
+ ...config,
111
+ ...(config.transactionRoots
112
+ ? { transactionRoots: config.transactionRoots.map((r) => expandHomePath(r.trim())) }
113
+ : {}),
114
+ };
115
+ baseWorkspace =
116
+ baseWorkspace !== undefined ? expandHomePath(baseWorkspace.trim()) : baseWorkspace;
93
117
  const requestedMode = config.mode ?? DEFAULT_EFFECT_RUN_MODE;
94
118
  const untrustedAdmission = config.untrustedAdmission ?? 'refuse';
95
119
  let mode = requestedMode;
@@ -15,7 +15,7 @@ export { TurnFileUndoLog, commitSessionFileUndo, discardSessionFileUndo, resolve
15
15
  export type { SessionUndoPaths, FileUndoEntry, DiscardFileEffectsResult, DiscardConflictReason, } from './undo-log.js';
16
16
  export { isProbablyText, reverseAgentOverwrite, merge3Lines } from './undo-merge.js';
17
17
  export { snapshotShellRoots, captureShellInventory, diffShellInventory, journalShellDiff, writeNotReversed, } from './shell-journal.js';
18
- export { resolveEffectiveEffectPolicy, isPathAllowed, isToolAllowedOnSurface, gateEffect, DEFAULT_EFFECT_RUN_MODE, readSessionEffectOverrides, normalizeTransactionRoots, mergeTransactionRoots, SESSION_EFFECT_OVERRIDES_KEY, } from './effect-policy.js';
18
+ export { resolveEffectiveEffectPolicy, requiresJail, isPathAllowed, isToolAllowedOnSurface, gateEffect, DEFAULT_EFFECT_RUN_MODE, readSessionEffectOverrides, normalizeTransactionRoots, mergeTransactionRoots, SESSION_EFFECT_OVERRIDES_KEY, } from './effect-policy.js';
19
19
  export type { UntrustedAdmission, ToolSurface, SecurityDegradation, EffectiveEffectPolicy, SessionEffectOverrides, } from './effect-policy.js';
20
20
  export { runWithToolLimits, resolveToolTimeoutMs, ToolTimeoutError, } from './resource-limits.js';
21
21
  export type { ToolRunLimits } from './resource-limits.js';
@@ -11,7 +11,7 @@ export { DEFAULT_TOOL_ISOLATION, resolveToolIsolationCwd, safeSessionDirSegment,
11
11
  export { TurnFileUndoLog, commitSessionFileUndo, discardSessionFileUndo, resolveSessionUndoPaths, resolveSessionUndoOnClose, } from './undo-log.js';
12
12
  export { isProbablyText, reverseAgentOverwrite, merge3Lines } from './undo-merge.js';
13
13
  export { snapshotShellRoots, captureShellInventory, diffShellInventory, journalShellDiff, writeNotReversed, } from './shell-journal.js';
14
- export { resolveEffectiveEffectPolicy, isPathAllowed, isToolAllowedOnSurface, gateEffect, DEFAULT_EFFECT_RUN_MODE, readSessionEffectOverrides, normalizeTransactionRoots, mergeTransactionRoots, SESSION_EFFECT_OVERRIDES_KEY, } from './effect-policy.js';
14
+ export { resolveEffectiveEffectPolicy, requiresJail, isPathAllowed, isToolAllowedOnSurface, gateEffect, DEFAULT_EFFECT_RUN_MODE, readSessionEffectOverrides, normalizeTransactionRoots, mergeTransactionRoots, SESSION_EFFECT_OVERRIDES_KEY, } from './effect-policy.js';
15
15
  export { runWithToolLimits, resolveToolTimeoutMs, ToolTimeoutError, } from './resource-limits.js';
16
16
  export { TurnMemoryJournal, JournaledMemoryStore, createMemoryRestorer, discardMemoryUndo, } from './memory-undo.js';
17
17
  export { resolveToolCapabilities, deniesReducedSurface, BUILTIN_TOOL_CAPABILITIES, REDUCED_DENIED_CAPABILITIES, } from './tool-capabilities.js';
@@ -5,6 +5,7 @@
5
5
  * 本模块解析「本 Run 的 toolRuntime.cwd」,不引入分布式文件锁。
6
6
  */
7
7
  import { isAbsolute, join, resolve, sep } from 'node:path';
8
+ import { expandHomePath } from '../../../paths.js';
8
9
  import { toSessionFileName } from '@octopi-agent/core/session-filename.js';
9
10
  /**
10
11
  * 缺省隔离模式。
@@ -35,7 +36,10 @@ export function safeSessionDirSegment(sessionId) {
35
36
  * @returns 工具 cwd 与生效模式
36
37
  */
37
38
  export function resolveToolIsolationCwd(input) {
38
- const base = input.baseCwd?.trim() ? input.baseCwd.trim() : undefined;
39
+ // `~` 形态在此展开(trim → expand):toolRuntime.cwd 必须与 eff.allowRoots
40
+ // (resolveEffectiveEffectPolicy 同源展开)一致,否则 strict 匹配失败、
41
+ // session-subdir 会 mkdir 出字面 `~` 目录(留观② P1-1)。
42
+ const base = input.baseCwd?.trim() ? expandHomePath(input.baseCwd.trim()) : undefined;
39
43
  const mode = input.mode;
40
44
  if (mode === 'session-subdir' && base) {
41
45
  const segment = safeSessionDirSegment(input.sessionId);
@@ -9,6 +9,7 @@ import { spawn } from 'node:child_process';
9
9
  import { realpath, unlink, writeFile } from 'node:fs/promises';
10
10
  import { homedir, tmpdir } from 'node:os';
11
11
  import { join, resolve } from 'node:path';
12
+ import { StringDecoder } from 'node:string_decoder';
12
13
  import { assessL4ProcessMinimum, killProcessTree, probeProcessIsolation, scrubEnv, supervisedSpawnProfile, } from './process-isolation.js';
13
14
  /**
14
15
  * Supervised process runner: tree-killable spawn with scrubbed env.
@@ -79,6 +80,27 @@ export class ProcessSandbox {
79
80
  const start = Date.now();
80
81
  let stdout = '';
81
82
  let stderr = '';
83
+ // 输出上限按原始字节计(stdout/stderr 各自独立计):字符数远小于字节数,
84
+ // 旧口径会让上限推迟触发、放走 ~3x 字节。计数含被丢弃块,故已捕获文本恒 ≤
85
+ // 上限;usage().outputBytes 只计已捕获字节(`captured*`,见下方 usage 调用)。
86
+ let stdoutBytes = 0;
87
+ let stderrBytes = 0;
88
+ // 已捕获原始字节:usage 的唯一口径。不能用 byteLength(文本) 代替——被切断的
89
+ // 多字节字符解码后是 3 字节的 U+FFFD,按文本重算会虚高(也说明必须用
90
+ // StringDecoder 跨块解码,逐块 toString 会让 stdout/stderr 文本本身被污染)。
91
+ let stdoutCaptured = 0;
92
+ let stderrCaptured = 0;
93
+ const stdoutDecoder = new StringDecoder('utf8');
94
+ const stderrDecoder = new StringDecoder('utf8');
95
+ let decodersFlushed = false;
96
+ /** 冲刷解码器尾部:未收尾的多字节字符在此输出(截断流输出 U+FFFD 是正确结果)。 */
97
+ const flushDecoders = () => {
98
+ if (decodersFlushed)
99
+ return;
100
+ decodersFlushed = true;
101
+ stdout += stdoutDecoder.end();
102
+ stderr += stderrDecoder.end();
103
+ };
82
104
  let terminated = false;
83
105
  let terminateReason = '';
84
106
  let settled = false;
@@ -116,24 +138,29 @@ export class ProcessSandbox {
116
138
  const onAbort = () => kill('Aborted');
117
139
  config?.signal?.addEventListener('abort', onAbort, { once: true });
118
140
  proc.stdout?.on('data', (data) => {
119
- if (stdout.length + data.length > opts.maxOutputBytes) {
141
+ stdoutBytes += data.length;
142
+ if (stdoutBytes > opts.maxOutputBytes) {
120
143
  kill('Output size limit exceeded');
121
144
  return;
122
145
  }
123
- stdout += data.toString('utf8');
146
+ stdoutCaptured += data.length;
147
+ stdout += stdoutDecoder.write(data);
124
148
  });
125
149
  proc.stderr?.on('data', (data) => {
126
- if (stderr.length + data.length > opts.maxOutputBytes) {
150
+ stderrBytes += data.length;
151
+ if (stderrBytes > opts.maxOutputBytes) {
127
152
  kill('Output size limit exceeded');
128
153
  return;
129
154
  }
130
- stderr += data.toString('utf8');
155
+ stderrCaptured += data.length;
156
+ stderr += stderrDecoder.write(data);
131
157
  });
132
158
  const timer = setTimeout(() => {
133
159
  kill(`Execution timeout (${opts.timeoutMs}ms)`);
134
160
  }, opts.timeoutMs);
135
161
  proc.on('close', (exitCode, signal) => {
136
- const usage = this.usage(start, stdout, stderr);
162
+ flushDecoders();
163
+ const usage = this.usage(start, stdoutCaptured, stderrCaptured);
137
164
  // null exitCode = signal death; never report that as success (exit 0)
138
165
  const code = typeof exitCode === 'number' ? exitCode : -1;
139
166
  finish({
@@ -151,7 +178,8 @@ export class ProcessSandbox {
151
178
  });
152
179
  });
153
180
  proc.on('error', (err) => {
154
- const usage = this.usage(start, stdout, stderr);
181
+ flushDecoders();
182
+ const usage = this.usage(start, stdoutCaptured, stderrCaptured);
155
183
  const isJailWrapper = profile.backend === 'linux-bwrap' || profile.backend === 'mac-seatbelt';
156
184
  if (config?.requireJail && isJailWrapper) {
157
185
  fail(new Error(`untrusted_jail_failed: jail spawn failed: ${err.message} (requireJail=true; refuse unsandboxed execute)`));
@@ -328,12 +356,12 @@ export class ProcessSandbox {
328
356
  },
329
357
  });
330
358
  }
331
- usage(start, stdout, stderr) {
359
+ usage(start, stdoutCaptured, stderrCaptured) {
332
360
  return {
333
361
  elapsedMs: Date.now() - start,
334
362
  peakMemoryBytes: -1,
335
363
  cpuTimeMs: -1,
336
- outputBytes: Buffer.byteLength(stdout, 'utf8') + Buffer.byteLength(stderr, 'utf8'),
364
+ outputBytes: stdoutCaptured + stderrCaptured,
337
365
  };
338
366
  }
339
367
  }
@@ -18,6 +18,12 @@ export interface AllowlistedRunOptions {
18
18
  timeoutMs?: number;
19
19
  /** Journal write effects via shell-journal (default true for mutating tools) */
20
20
  journal?: boolean;
21
+ /**
22
+ * Apply the tool output gate (caps output toward model context). Default true.
23
+ * Structured consumers (UI snapshots) pass false and cap on their own terms —
24
+ * the gate cuts at a char budget and would slice parse records mid-stream.
25
+ */
26
+ applyOutputGate?: boolean;
21
27
  }
22
28
  export interface AllowlistedRunResult {
23
29
  stdout: string;
@@ -83,6 +83,23 @@ export async function runAllowlistedArgv(options) {
83
83
  catch {
84
84
  // Journal failure must not drop the business result (matches shell tool).
85
85
  }
86
+ if (options.applyOutputGate === false) {
87
+ // Structured consumers cap on their own terms (parse, then slice). The only
88
+ // stream cut left is the sandbox output cap, which kills the process *before*
89
+ // appending the offending chunk — so length heuristics cannot see it; the
90
+ // honest signal is the terminate reason (verified in sandbox.ts).
91
+ return {
92
+ stdout: sandboxResult.stdout,
93
+ stderr: sandboxResult.stderr,
94
+ exitCode: sandboxResult.exitCode,
95
+ durationMs: sandboxResult.usage.elapsedMs,
96
+ truncated: sandboxResult.terminated && sandboxResult.terminateReason === 'Output size limit exceeded',
97
+ rawStdoutLength: sandboxResult.stdout.length,
98
+ terminated: sandboxResult.terminated,
99
+ terminateReason: sandboxResult.terminateReason,
100
+ isolation: sandboxResult.isolation,
101
+ };
102
+ }
86
103
  try {
87
104
  const { applyToolOutputGate, resolveSupportBinding } = await import('../../../context/capabilities/summary/index.js');
88
105
  const binding = resolveSupportBinding('shell', undefined, 8000);
@@ -49,26 +49,19 @@ export function createFileSearchTool(options) {
49
49
  name: 'file_search',
50
50
  capabilities: ['fs-read'],
51
51
  description: 'Search file contents (like grep/rg) with structured results. ' +
52
- 'Provide `pattern` (one term) or `patterns` (any-of literals). ' +
53
- 'Default pattern_mode=auto compiles as regex only on strong signals: ' +
54
- 'anchors (^…$), escapes (\\d \\w \\s), `.*`/`.+`, `{n}` quantifiers. ' +
55
- 'In auto, `a|b` is a literal OR of trimmed branches (`.` is a literal dot, not a wildcard); ' +
56
- 'an empty branch (`foo|`, `|`) falls back to whole-term literal. ' +
57
- 'Code tokens stay literal: `arr[0]`, `useState()`, `a+b`, `C++`, `foo.bar`, `memory*`. ' +
58
- 'Set pattern_mode="regex" or "literal" to force. ' +
59
- "Glob filters by root-relative path (always case-insensitive): '*.md' (any depth), 'src/**/*.ts', '**/memory*.md'. " +
60
- "`**` crosses directories, `*` does not. " +
61
- 'Path: a directory to walk recursively, or a single file path to search just that file. ' +
52
+ 'Provide `pattern` (one term) or `patterns` (any-of literals) — match semantics on those params. ' +
53
+ '`glob` filters by relative path (always case-insensitive; `**` crosses directories, `*` does not). ' +
54
+ '`path` = root dir to walk recursively, or one file to search. ' +
62
55
  'Empty results include diagnostics.hints for how to retry. ' +
63
- 'Default case-insensitive content match; set case_sensitive=true for exact case. ' +
64
- 'Files are read as line streams; max_file_bytes (default 50MB) skips oversized files. ' +
65
- 'Files whose first 4KB contains a NUL byte are treated as binary and skipped.',
56
+ 'Default case-insensitive content match (`case_sensitive=true` for exact). ' +
57
+ 'Files scanned as line streams; `max_file_bytes` skips larger files; first 4KB NUL ⇒ treated as binary.',
66
58
  parameters: {
67
59
  pattern: {
68
60
  type: 'string',
69
- description: 'Single search term. Auto: regex only for ^ $ \\d .* {n}; ' +
61
+ description: 'Single search term. Auto: regex only on strong signals — anchors (^…$), ' +
62
+ 'escapes (\\d \\w \\s \\b …) or escaped metachars, `.*`/`.+`, `{n}`; ' +
70
63
  '`a|b` = literal OR of trimmed branches (empty branch → whole-term literal); ' +
71
- 'everything else is literal text.',
64
+ 'everything else is literal text (e.g. `arr[0]`, `C++`, `foo.bar`).',
72
65
  },
73
66
  patterns: {
74
67
  type: 'array',
@@ -83,11 +76,11 @@ export function createFileSearchTool(options) {
83
76
  glob: {
84
77
  type: 'string',
85
78
  description: "Path glob relative to root (case-insensitive), e.g. '*.md', 'src/**/*.ts', '**/memory*.md'. " +
86
- 'Matches relative path; bare `*` does not cross directories.',
79
+ 'Matches relative path; bare name (no `/`) matches at any depth; `*` does not cross directories.',
87
80
  },
88
81
  pattern_mode: {
89
82
  type: 'string',
90
- description: 'How to compile pattern/patterns (default: auto)',
83
+ description: 'How to compile pattern/patterns (default: auto; set "regex"/"literal" to force)',
91
84
  enum: ['auto', 'literal', 'regex'],
92
85
  },
93
86
  regex: {