@menghuan1918/dsh-apollo 0.4.0 → 0.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@menghuan1918/dsh-apollo",
-  "version": "0.4.0",
-  "description": "DSH plugin: 流程技能、工程模式、Codex/Claude 可续接子代理与统一设置。纯 ESM，无构建步骤。",
+  "version": "0.5.0",
+  "description": "DSH plugin bundle: workflow skills, engineering presets, independent better-goal / better-subagent / better-compact integration, and a minimal job exit guard. Pure ESM, no build step.",
   "license": "GPL-3.0-or-later",
   "repository": {
     "type": "git",
@@ -21,11 +21,12 @@
   },
   "scripts": {
     "test": "node --test",
-    "prompts": "node scripts/render-prompts.mjs"
+    "prompts": "node scripts/render-prompts.mjs",
+    "smoke": "node scripts/runtime-smoke.mjs"
   },
   "files": [
     "src",
-    "docs",
+    "docs/DEVELOPMENT.md",
     "skills",
     "presets",
     "third-party",
@@ -53,7 +54,9 @@
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "~3.18.4",
-    "dsh-better-goal": "0.1.0"
+    "@menghuan1918/dsh-better-subagent": "0.1.0",
+    "dsh-better-compact": "0.1.0",
+    "dsh-better-goal": "0.2.0"
   },
   "peerDependencies": {
     "react": "^18.2.0"

package/presets/eng/plugins/exit-guard/index.js

@@ -1,96 +1,84 @@
 /**
- * `eng-exit-guard` — 工程模式退出守卫（预设本地插件）。
+ * `eng-exit-guard` — 工程模式退出守卫（预设本地插件），只管后台任务。
  *
- * pi-atlas task guard 的 DSH 等价物：回合即将结束时（`agent/turn-stopping`，
- * serial 事件——监听器跑完后 agent-loop 会重查 inbox，`agent.steer()` 加入的
- * next-step 消息使回合不关闭），若本代理仍有运行中的直接子代理或后台任务，
- * 注入一条提醒强制回合继续，直到 wait_subagent / job_output 等待收取、
- * job_kill 停止，或用户中断（被中断的回合在 dispatch 前即 throwIfAborted，
+ * pi-atlas task guard 的 DSH 等价物中属于 Apollo 的那一半：回合即将结束时
+ * （`agent/turn-stopping`，serial 事件——监听器跑完后 agent-loop 会重查 inbox，
+ * `agent.steer()` 加入的 next-step 消息使回合不关闭），若本代理仍有运行中的
+ * DSH 后台 job，注入一条提醒强制回合继续，直到 `job_output` 收取、
+ * `job_kill` 停止，或用户中断（被中断的回合在 dispatch 前即 throwIfAborted，
  * 天然不触发本守卫——Esc 始终是逃生口）。
  *
- * 无豁免机制（曾有 exitGuardIgnore 子串清单，因会被用来静默绕过守卫而移除
- * ——实测有会话中 agent 被拦一次后自行写入豁免，后续回合全部静默放行）：
+ * 运行中**直接子代理**的拦截不在这里：0.5.0 起由 dsh-better-subagent 的
+ * `childExitGuard` 拥有（`agent/turn-stopping` 上的独立监听器，独立开关）。
+ * 本插件只读 Apollo 的 `exitGuard`（job/通用），不导入、不复制子代理判断。
+ *
+ * 无豁免机制（曾有 exitGuardIgnore 子串清单，因会被用来静默绕过守卫而移除）：
  * 任何存活的后台 job 都必须被收取或停止，回合才能收尾。需要跨回合常驻的
  * 服务（dev server、watcher）用 pm2/systemd/裸 nohup 等脱离 DSH job 注册表
- * 的方式管理——守卫只看本地 job 注册表与直接子代理。
+ * 的方式管理——守卫只看本地 job 注册表。
  *
  * 每次事件读取当前 profile 的 Apollo Config.exitGuard（默认关闭）。
  * 设置保存后即时生效；旧配置只由宿主执行一次性导入。
- * 查询失败（listChildren / jobs.list 抛错）按 fail-open 处理：告警并放行本次
- * 回合结束，避免查询故障把回合卡死。
+ * 查询失败（jobs.list 抛错）按 fail-open 处理：告警并放行本次回合结束。
  *
- * 零 bare import（同 wait-subagent 约束）；消息构造参照 goal-round-driver /
- * repeat-tool-reminder 的 plain-object 模式。
+ * 零 bare import（预设本地插件约束）；消息 source 使用生产者自有 kind
+ * `better-apollo-job-exit-guard`——session format v4 拒绝旧的
+ * `{kind:'plugin', plugin}` 形状。
  */
 
 import { currentConfig } from '../../../../src/config.js'
 
 export const name = 'eng-exit-guard'
 
-export const inject = ['subagents', 'agents']
-
 /** 后台任务终态（dsh-jobs-local isTerminal 同款）。 */
 const JOB_TERMINAL = new Set(['completed', 'killed', 'failed'])
 
+/** Producer-owned source kind accepted by session format v4. */
+export const NOTICE_SOURCE_KIND = 'better-apollo-job-exit-guard'
+
 /** 渲染一条运行项清单行。 */
-function lineOf(prefix, id, detail) {
-  return `  - ${prefix} ${id}${detail === undefined || detail === '' ? '' : ` (${detail})`}`
+function lineOf(job) {
+  const detail = job.label === undefined ? job.kind : `${job.label}, ${job.kind}`
+  return `  - background job ${job.id} (${detail})`
 }
 
 /**
  * 构造 steer 提醒消息（模型可见，进入会话日志）。
- * @param children - 运行中的直接子代理 listChildren 条目。
  * @param jobs - 运行中的后台任务快照。
  * @returns 一条 user 角色的 plugin notice 消息。
  */
-function buildMessage(children, jobs) {
-  const lines = []
-  for (const child of children) {
-    // 0.1.1-rc.2 的条目是 meta:{mode,label}，0.1.2 起 mode/label 升为顶级；
-    // 兼容回退只影响展示措辞，绝不抛错。
-    lines.push(lineOf('subagent', child.id, child.label ?? child.meta?.label))
-  }
-  for (const job of jobs) {
-    lines.push(lineOf('background job', job.id, job.label === undefined ? job.kind : `${job.label}, ${job.kind}`))
-  }
+export function buildJobGuardMessage(jobs) {
   const text = [
     'This background work is still running, so the turn cannot end yet:',
-    ...lines,
+    ...jobs.map(lineOf),
     '',
-    'Wait for running subagents with wait_subagent (use send_message to continue one), '
-      + 'collect background command results with job_output, and stop work you no longer need with job_kill. Finish only after all of it is handled.',
+    'Collect background command results with job_output, and stop work you no longer need with job_kill. '
+      + 'Finish only after all of it is handled.',
   ].join('\n')
   return {
     role: 'user',
     content: [{ type: 'text', text }],
     source: {
-      kind: 'plugin',
-      plugin: 'eng-exit-guard',
+      kind: NOTICE_SOURCE_KIND,
       form: 'notice',
-      summary: `运行中的后台工作阻止回合结束（子代理 ${children.length}，后台任务 ${jobs.length}）`,
+      summary: `运行中的后台任务阻止回合结束（${jobs.length}）`,
     },
     id: crypto.randomUUID(),
   }
 }
 
 /**
- * 收集本代理仍在运行的后台工作。
- * @param ctx - 预设插件上下文（subagents / agents 注入，jobs 可选）。
+ * 收集本代理仍在运行的后台任务。
+ * @param ctx - 预设插件上下文（jobs 可选，经 ctx.get 读取）。
  * @param agent - 回合即将结束的代理。
- * @returns `{ children, jobs }`；查询失败抛出由调用方按 fail-open 处理。
+ * @returns 运行中的 job 数组；查询失败抛出由调用方按 fail-open 处理。
  */
-async function collectRunning(ctx, agent) {
-  const children = []
-  for (const entry of await ctx.subagents.listChildren(agent.id)) {
-    if (ctx.agents.get(entry.id)?.status === 'running') children.push(entry)
-  }
+export function collectRunningJobs(ctx, agent) {
   const jobs = ctx.get('jobs')
-  const runningJobs = jobs === undefined
-    ? []
-    // 0.1.7 起 JobRegistry.list 的参数是 SessionId（0.1.6 及以前是 Agent 对象）：
-    // 传 Agent 对象不报错但恒不匹配，守卫会静默看不见任何 owned 后台任务。
-    : jobs.list(agent.id).filter((job) => !JOB_TERMINAL.has(job.status))
-  return { children, jobs: runningJobs }
+  if (jobs === undefined) return []
+  // 0.1.7 起 JobRegistry.list 的参数是 SessionId（0.1.6 及以前是 Agent 对象）：
+  // 传 Agent 对象不报错但恒不匹配，守卫会静默看不见任何 owned 后台任务。
+  return jobs.list(agent.id).filter((job) => !JOB_TERMINAL.has(job.status))
 }
 
 export function apply(ctx) {
@@ -99,10 +87,10 @@ export function apply(ctx) {
     if (agent === undefined || payload?.signal?.aborted) return
     try {
       if (!currentConfig(ctx).exitGuard) return
-      const { children, jobs } = await collectRunning(ctx, agent)
-      if (children.length === 0 && jobs.length === 0) return
+      const jobs = collectRunningJobs(ctx, agent)
+      if (jobs.length === 0) return
       if (payload.signal?.aborted) return
-      agent.steer(buildMessage(children, jobs))
+      agent.steer(buildJobGuardMessage(jobs))
     } catch (error) {
       // fail-open：查询或注入失败时放行本次回合结束，守卫不应卡死会话。
       ctx.logger?.warn?.(`eng-exit-guard: guard skipped: ${error instanceof Error ? error.message : String(error)}`)

package/presets/eng/plugins/mode-instructions/index.js

@@ -2,34 +2,29 @@
  * `eng-mode-instructions` — preset-scoped prompt section for 工程模式
  * (`eng`) and 工程(PTC)模式 (`eng-ptc`).
  *
- * Carries what no other surface states: the general engineering discipline
- * (moved out of the user-global ~/.dsh/AGENTS.md, which keeps only
- * machine-local conventions), the delegation policy, the subagent model tiers
- * rendered from Apollo settings (`tiers.*`), and the exit guard contract while
- * that switch is on. Tool mechanics, background-job etiquette and run_code
- * syntax live in the harness prompt and tool descriptions and are NOT
- * repeated here.
+ * 0.5.0 boundary: this section carries ONLY what still belongs to Apollo — the
+ * general engineering discipline (moved out of the user-global ~/.dsh/AGENTS.md,
+ * which keeps only machine-local conventions) and the job-only exit-guard
+ * contract while that switch is on.
  *
- * The text is a function re-rendered per request from the live Apollo config,
- * so settings edits apply without remounting; an edit costs the prefix cache
- * once, which is acceptable for rarely changed settings. The row config
- * `ptc: true` (set by eng-ptc) adds a rule for fanning out subagents inside
- * one run_code program (workflow usage is left to the harness tool guidance); run_code mechanics themselves
- * come from the harness `tools:sdk` / `tools:ptc-only` sections.
+ * Subagent delegation, fast/quality model tiers, PTC fan-out, the CLI catalog
+ * and the running-child guard are owned by dsh-better-subagent's per-Agent
+ * prompt sections (registered on `agent/created`). Apollo keeps no second
+ * generator and no `ptc` switch: the new plugin detects `eng-ptc` itself.
+ * Tool mechanics, background-job etiquette and run_code syntax live in the
+ * harness prompt and tool descriptions and are not repeated here.
+ *
+ * The text is a function re-rendered per request from the live Apollo config, so
+ * settings edits apply without remounting; an edit costs the prefix cache once,
+ * which is acceptable for rarely changed settings.
  */
 
-import z from '@deepseek-ai/schemastery'
 import { currentConfig } from '../../../../src/config.js'
 
 export const name = 'eng-mode-instructions'
 
 export const inject = ['systemPrompt']
 
-export const Config = z.object({
-  /** Render the PTC variant (eng-ptc). */
-  ptc: z.boolean().default(false),
-})
-
 const PRINCIPLES = `# Engineering mode
 
 For coding and infrastructure work. These are defaults; explicit user instructions take precedence.
@@ -69,56 +64,25 @@ For coding and infrastructure work. These are defaults; explicit user instructio
 - Never sleep longer than 60s at once; for longer waits use stepped probes, sentinel files, or completion notices.
 - Run services that must outlive the turn (dev servers, watchers) under pm2/nohup outside the job registry, and say which ones are still running when you finish.`
 
-const DELEGATION_HEAD = `## Delegation
-- Subagents cannot see this conversation: state the goal, write scope, deliverable, and verification, and give real file paths for prior outputs.
-- Opening reconnaissance: when starting non-trivial work in an unfamiliar or large codebase, immediately dispatch fast-tier scouts in parallel (structure, relevant modules, conventions, test entry points), all in one message; the main agent reads only the instruction files that define the task. A scout prompt needs only goal, boundaries, and deliverable.
-- Delegate read-only, parallelizable, stateless investigation by default instead of trying it in the main thread first; when a new unknown appears mid-task and 1–2 rounds of digging do not converge, delegate it.
-- Implementation chunks with non-overlapping write scopes can run in parallel; keep linear work, tightly coupled changes, and debugging that needs live state in the main thread.`
-
-const FANOUT_PTC = '- For repeated same-shaped work, dispatch all subagents inside one run_code program, then collect them with wait_subagent.'
-
-const DELEGATION_TAIL = `- When you need a subagent's result, wait patiently with wait_subagent. Do not poll or prod it with send_message; send a message only to give it genuinely new information or a correction.
-- The main agent owns integration, review, and final verification. Subagent reports are leads, not evidence: check the actual changes yourself.
-- When a subagent ends in an error or empty result, read why, fix the cause, and re-dispatch once; take over in the main thread only if it fails again without an external blocker, and say why.`
-
-const EXIT_GUARD = `## Exit guard
-- If subagents or background commands are still running when the turn would end, the system injects a reminder and the turn continues. Collect them with wait_subagent / job_output, stop unneeded ones with job_kill, then finish.`
-
-/** One tier as model-facing argument text; an unset tier inherits the parent route. */
-export function renderTier(tier) {
-  if (!tier?.provider || !tier?.model) return 'omit provider / model / reasoning_effort to inherit the parent route'
-  const parts = [`provider: \`${tier.provider}\``, `model: \`${tier.model}\``]
-  if (tier.reasoningEffort) parts.push(`reasoning_effort: \`${tier.reasoningEffort}\``)
-  return parts.join(' · ')
-}
+const JOB_EXIT_GUARD = `## Exit guard
+- If background commands are still running when the turn would end, the system injects a reminder and the turn continues. Collect them with job_output, stop unneeded ones with job_kill, then finish.`
 
 /**
- * Render the full section text.
- * @param config - normalized Apollo config (`exitGuard`, `tiers`).
- * @param options - `{ ptc }` from this row's config.
+ * Render the section text.
+ * @param config - normalized Apollo config (`exitGuard`).
  * @returns the section markdown.
  */
-export function renderInstructions(config, options = {}) {
-  const tiers = `## Subagent model tiers
-- Fast tier (exploration, reconnaissance, mechanical analysis, batch triage): ${renderTier(config.tiers?.fast)}
-- Quality tier (complex implementation, debugging, review, design): ${renderTier(config.tiers?.quality)}
-- Start exploration on the fast tier; when coverage falls short or key questions remain, re-dispatch the unresolved part on the quality tier. Escalating means re-dispatching, not modifying an existing subagent.
-- subagent_fork takes no model choice: it keeps the parent route to reuse the prefix cache.`
-  const blocks = [
-    PRINCIPLES,
-    [DELEGATION_HEAD, ...(options.ptc ? [FANOUT_PTC] : []), DELEGATION_TAIL].join('\n'),
-    tiers,
-  ]
-  if (config.exitGuard) blocks.push(EXIT_GUARD)
+export function renderInstructions(config) {
+  const blocks = [PRINCIPLES]
+  if (config?.exitGuard) blocks.push(JOB_EXIT_GUARD)
   return blocks.join('\n\n')
 }
 
-export function apply(ctx, config) {
-  const options = { ptc: config?.ptc === true }
+export function apply(ctx) {
   ctx.effect(() => ctx.systemPrompt.section({
     name: 'eng:mode-instructions',
     order: 1,
     interpolate: false,
-    text: () => renderInstructions(currentConfig(ctx), options),
+    text: () => renderInstructions(currentConfig(ctx)),
   }), 'eng-mode-instructions.section()')
 }

package/presets/eng-ptc.patch.yml

@@ -7,8 +7,9 @@
 #     run_code TypeScript SDK (needs the host `ptc-runtime` row);
 #   - `workflow-ptc` and `tool-workflow` disabled: PTC fans out by calling
 #     subagent several times inside one run_code program instead;
-# plus `eng-mode-instructions { ptc: true }`, which adds the rule for fanning
-# out subagents inside one run_code program. Preset-local plugins reuse the eng modules.
+# Preset-local plugins reuse the eng modules. Subagent fan-out wording is owned
+# by dsh-better-subagent (it detects the `eng-ptc` preset itself), so this row
+# carries no `ptc` switch.
 # tests/upstream-drift.test.mjs checks this file against both eng and the
 # upstream `ptc` preset; edit eng first, then redo these deltas.
 #
@@ -96,8 +97,8 @@
               compaction: true
               toolResultPruner: true
             config:
-              - id: compaction-basic
-                name: '@deepseek-ai/dsh-compaction-basic'
+              - id: dsh-better-compact-engine
+                name: dsh-better-compact/engine
 
               - id: command-compact
                 name: '@deepseek-ai/dsh-command-compact'
@@ -174,13 +175,8 @@
             name: '@deepseek-ai/dsh-plugin-market/tools'
             disabled: true
 
-          - id: tool-wait-subagent
-            name: '@menghuan1918/dsh-apollo/presets/eng/plugins/wait-subagent/index.js'
-
           - id: eng-exit-guard
             name: '@menghuan1918/dsh-apollo/presets/eng/plugins/exit-guard/index.js'
 
           - id: eng-mode-instructions
             name: '@menghuan1918/dsh-apollo/presets/eng/plugins/mode-instructions/index.js'
-            config:
-              ptc: true

package/presets/eng.patch.yml

@@ -179,15 +179,20 @@
 
           # ── compaction ──────────────────────────────────────────────────────────────
 
-          # `compaction-basic` reads `toolResultPrune` through `ctx.get`, so the pruner must
-          # share this realm rather than sit outside it.
+          # The compaction service is preset-owned in the Web composition. The
+          # native `compaction-basic` row is replaced by the independent
+          # dsh-better-compact engine (same stable row id/name as its standalone
+          # bundle); it keeps the native token meter, safe-cut selection,
+          # retention, locking, durable checkpoint transaction and `/compact`,
+          # and adds the native/goal/handoff summary modes. The host-plane
+          # engine inserted by the top-level patch detects this preset-owned
+          # service and stays out of the way, so there is one engine per realm.
           #
-          # `tokenMeter` is deliberately NOT in this realm: the meter stays on the HOST
-          # plane, and the rows here resolve that one instance. It takes no configuration,
-          # keys every fold by Session, and owns the context-meter projection units the
-          # browser reads for every session — behind a realm those units would come and go
-          # with whichever presets happen to be mounted. What a preset chooses is whether
-          # its agent compacts at all, which is `compaction-basic` below.
+          # The engine reads `toolResultPrune` through `ctx.get`, so the pruner
+          # must share this realm rather than sit outside it.
+          #
+          # `tokenMeter` is deliberately NOT in this realm: the meter stays on the
+          # HOST plane, and the rows here resolve that one instance.
           - id: compaction
             name: cordis:group
             group: true
@@ -195,8 +200,8 @@
               compaction: true
               toolResultPruner: true
             config:
-              - id: compaction-basic
-                name: '@deepseek-ai/dsh-compaction-basic'
+              - id: dsh-better-compact-engine
+                name: dsh-better-compact/engine
 
               - id: command-compact
                 name: '@deepseek-ai/dsh-command-compact'
@@ -301,38 +306,26 @@
             name: '@deepseek-ai/dsh-plugin-market/tools'
             disabled: true
 
-          # ── subagent waiting ─────────────────────────────────────────────────────────
-
-          # Preset-local plugin: explicit wait for one continuable child to settle, so
-          # the agent can block on a specific subagent (pi-style await_task semantics)
-          # without giving up send_message continuations. The module specifier is a
-          # bare subpath of this package (@menghuan1918/dsh-apollo/presets/eng/plugins/...):
-          # config.plugins names resolve from the profile directory's node_modules,
-          # where this package is installed or linked; it has zero bare imports on
-          # purpose.
-          - id: tool-wait-subagent
-            name: '@menghuan1918/dsh-apollo/presets/eng/plugins/wait-subagent/index.js'
-
           # ── exit guard ───────────────────────────────────────────────────────────────
           #
-          # Preset-local plugin: pi-atlas 式退出守卫。回合结束（agent/turn-stopping）
-          # 时若有运行中的直接子代理或后台任务，注入 next-step 提醒（agent.steer）
-          # 强制回合继续，直到 wait_subagent / job_output / job_kill 处理完毕或用户
-          # 中断（被中断回合不触发）。开关为正式 Config.exitGuard，默认关闭，
-          # 每次事件读取当前值，设置保存后即时生效。监听器注册型
-          # 插件，无服务发布，无需 realm。
+          # Preset-local plugin: pi-atlas 式退出守卫（仅后台任务）。回合结束
+          # （agent/turn-stopping）时若本会话仍有运行中的 DSH 后台 job，注入
+          # next-step 提醒（agent.steer）强制回合继续，直到 job_output / job_kill
+          # 处理完毕或用户中断（被中断回合不触发）。运行中子代理的拦截由
+          # dsh-better-subagent 的 childExitGuard 拥有，这里不再重复判断。开关为
+          # Apollo Config.exitGuard，默认关闭，每次事件读取当前值，设置保存后即时
+          # 生效。监听器注册型插件，无服务发布，无需 realm。
           - id: eng-exit-guard
             name: '@menghuan1918/dsh-apollo/presets/eng/plugins/exit-guard/index.js'
 
           # ── mode instructions ────────────────────────────────────────────────────────
 
-          # Preset-local prompt section carrying the engineering discipline (moved out
-          # of the user-global ~/.dsh/AGENTS.md), the delegation policy, the model
-          # tiers rendered from Apollo settings (`tiers.*`), and the exit guard
-          # contract when that switch is on. Registered as a system-prompt section
-          # (order 1, right after the persona slot) so it is scoped to sessions
-          # mounted on this preset; its text is re-rendered per request from the live
-          # Apollo config. `ptc: true` (set by eng-ptc) adds the rule for fanning
-          # out subagents inside one run_code program.
+          # Preset-local prompt section carrying only the general engineering
+          # discipline (moved out of the user-global ~/.dsh/AGENTS.md) and the
+          # job-only exit guard contract. Subagent delegation, model tiers, PTC
+          # fan-out and the child guard are rendered by dsh-better-subagent's own
+          # per-Agent sections — Apollo keeps no second generator. Registered as a
+          # system-prompt section (order 1, right after the persona slot) and
+          # re-rendered per request from the live Apollo config.
           - id: eng-mode-instructions
             name: '@menghuan1918/dsh-apollo/presets/eng/plugins/mode-instructions/index.js'