dsh-plugin-prompt-tool 0.1.4 → 0.2.0

package/{vendor → upstream}/dsh-anchored-standard/preset/instruction-hint.mjs

@@ -10,24 +10,35 @@
  *
  * Behavior:
  *  - After the session records its first durable promotion signal
- *    (`promoteOn`, default `either`), ONE hint message is injected (once per
- *    session — durable event scan, resume-safe), listing which instruction
- *    files were found:
+ *    (`promoteOn`, default `either`), ONE hint message is injected, listing
+ *    which instruction files were found:
  *      - user-global: `$DSH_HOME/AGENTS.md`
  *      - project chain: AGENTS.md / CLAUDE.md / AGENTS.local.md / CLAUDE.local.md
  *        walking up from the session cwd to the project root (a directory
  *        containing `.git`, or the cwd itself).
+ *  - The hint is ONCE PER SESSION, DERIVED FROM DURABLE EVENTS: the guard
+ *    scans the session log for an existing `instruction-hint` message (then
+ *    O(1)), so a process restart — whose in-memory state starts empty —
+ *    cannot inject a second copy. A duplicate would collide with the first
+ *    message's deterministic id (`instruction-hint-<sessionId>`) and break
+ *    history replay.
  *  - The hint instructs the model to READ the files before acting when
  *    relevant, without embedding their content.
  *  - Files are probed via `ctx.fs` (the host filesystem seam); a missing fs
  *    service or an unreadable probe degrades to no hint (never throws).
  *  - Pre-promotion requests get NO hint (matches the anchored bootstrap).
+ *  - Subagents skip the phase wait by default (their first request already
+ *    counts as promoted); `includeSubagents: true` makes a subagent's own
+ *    first reply or tool call open the hint — which also keeps the injection
+ *    out of the context gate's stripped first request (the gate strips
+ *    non-claimed messages while unpromoted).
  *
  * ROW ORDER: this plugin registers its `agent/pre-step` handler with
- * `prepend: true` and after `tool-bootstrap`, so it runs inside the
- * bootstrap's outermost strip — but it emits AFTER promotion, when the strip
- * is inactive. The hint source kind is `instruction-hint`, which is NOT in
- * `suppressedContextSources`, so it is never stripped.
+ * `prepend: true` and after `context-gate`/`tool-bootstrap`, so it runs
+ * inside the gate's outermost strip — but it emits AFTER promotion, when the
+ * strip is inactive. The hint source kind is `instruction-hint`, which is
+ * not in the gate's claimed-baseline allowlist, so the gate can strip it
+ * only while the session is unpromoted (never the intended path).
  */
 
 import { createEpochPromotion } from './compaction-epoch.mjs'
@@ -52,6 +63,18 @@ function parsePromoteOn(value) {
   throw new TypeError(`${name}: promoteOn must be one of "tool-call", "assistant-message", "either"; got ${JSON.stringify(value)}`)
 }
 
+/** Every config key this plugin accepts — anything else is a typo. */
+const ALLOWED_KEYS = new Set(['promoteOn', 'includeSubagents'])
+
+/** Validate an optional boolean flag with a default. */
+function booleanOption(value, field, fallback) {
+  if (value === undefined) return fallback
+  if (typeof value !== 'boolean') {
+    throw new TypeError(`${name}: ${field} must be a boolean`)
+  }
+  return value
+}
+
 /** Find the project root: first ancestor containing any root marker (e.g. .git). */
 async function findProjectRoot(fs, cwd, signal) {
   let current = cwd
@@ -103,12 +126,42 @@ function parentPath(path) {
 
 /** Register the post-promotion instruction-hint injector. */
 export function apply(ctx, config) {
-  const promoteEvents = parsePromoteOn(config.promoteOn)
-  const promotion = createEpochPromotion(promoteEvents)
+  const source = config === undefined ? {} : config
+  if (typeof source !== 'object' || source === null || Array.isArray(source)) {
+    throw new TypeError(`${name}: config must be an object`)
+  }
+  const unknown = Object.keys(source).filter((key) => !ALLOWED_KEYS.has(key))
+  if (unknown.length > 0) {
+    throw new TypeError(
+      `${name}: unknown config key(s) ${unknown.join(', ')} — allowed keys: ${[...ALLOWED_KEYS].sort().join(', ')}`,
+    )
+  }
+  const promoteEvents = parsePromoteOn(source.promoteOn)
+  const includeSubagents = booleanOption(source.includeSubagents, 'includeSubagents', false)
+  const promotion = createEpochPromotion(promoteEvents, { includeSubagents })
   ctx.on('session/event', (session, event) => promotion.observe(session, event))
 
-  /** Sessions that already received the hint. */
-  const hinted = new Set()
+  /**
+   * Sessions whose hint is already durable in the event log — the
+   * restart-safe replacement for an in-memory "already hinted" set. Seeded by
+   * a one-time scan, then maintained incrementally through `session/event`.
+   */
+  const hinted = new Map()
+  const hintIsDurable = (session) => {
+    const known = hinted.get(session.id)
+    if (known !== undefined) return known
+    const found = (Array.isArray(session.events) ? session.events : []).some((event) =>
+      event.type === 'user/message' && event.data?.source?.kind === 'instruction-hint',
+    )
+    hinted.set(session.id, found)
+    return found
+  }
+  ctx.on('session/event', (session, event) => {
+    if (event.type === 'user/message' && event.data?.source?.kind === 'instruction-hint') {
+      hinted.set(session.id, true)
+    }
+  })
+
   let warned = false
   const warnOnce = (message) => {
     if (warned) return
@@ -125,8 +178,8 @@ export function apply(ctx, config) {
     try {
       if (promotion.status(agent).promoted !== true) return decision
       const session = agent.session
-      if (session === undefined || hinted.has(session.id)) return decision
-      hinted.add(session.id)
+      if (session === undefined || hintIsDurable(session)) return decision
+      hinted.set(session.id, true)
 
       const fs = ctx.get('fs')
       if (fs === undefined) return decision

package/{vendor → upstream}/dsh-anchored-standard/preset/tool-bootstrap.mjs

@@ -1,9 +1,9 @@
 /**
  * Anchored tool bootstrap — keep the FIRST model request on the Minimal
- * preset's REAL tool schema (persistent `bash` + `str_replace_editor`), free
- * of auto-injected workspace/skill context, then narrow the catalog to a
- * minimal RESIDENT set once the session has produced its first durable
- * promotion signal.
+ * preset's REAL tool schema (persistent `bash` + `str_replace_editor`), then
+ * narrow the catalog to a minimal RESIDENT set once the session has produced
+ * its first durable promotion signal. Injected-context control lives in the
+ * companion `context-gate` plugin, not here.
  *
  * The phase is derived from durable session events, so resume and reload
  * preserve it. By default (`promoteOn: 'either'`) a session promotes after the
@@ -39,18 +39,19 @@
  *     promotion — the next request's seed proposal carries the previous
  *     header's maxTokens forward, so the release must be explicit.
  *
- *  3. Injected reminders. dsh-agent-instructions and dsh-tool-skill inject
- *     workspace instructions (AGENTS.md) and the skill catalog into the first
- *     step as user messages whenever such content exists. With the skill
- *     catalog present the anchor did not reproduce at all (0/9); without it
- *     the same request reproduces at ~81%. Both message kinds are therefore
- *     stripped during bootstrap and allowed again after promotion. The
- *     stripped set is configurable via `suppressedContextSources` (default
- *     `['skill-catalog', 'agent-instructions']`); an explicitly empty array
- *     disables the context filter while keeping the tool bootstrap. A
- *     user-initiated skill gesture (`skill-invocation`) is NOT in the default
- *     set: it is not an automatic injection, and stripping it would lose the
- *     skill content once the gesture scrolls out of the per-step claim.
+ *  3. Injected context is NOT this plugin's concern: the companion
+ *     `context-gate` plugin (shared/context-gate.mjs, mounted as the FIRST
+ *     row) owns the unified injection control — runtime-context suppression
+ *     on the assembly path and a claimed-baseline deny on the pre-step
+ *     waterfall, both keyed to the same epoch-aware promotion phase. Mount it
+ *     separately for context control alone; this file narrows only the tool
+ *     catalog (plus the optional output cap below).
+ *
+ * SUBAGENTS: by default subagents (delegationDepth > 0) are always promoted
+ * (resident catalog from their first request). `includeSubagents: true`
+ * makes them follow the same bootstrap phase — their first request also sees
+ * the bootstrap pair, and their own first reply or tool call promotes them.
+ * Keep this flag in sync with the context-gate row's flag.
  *
  * POST-PROMOTION RESIDENT SET (local addition, user-measured): the promoted
  * phase does NOT dump the whole Standard catalog at once — that dump pulls
@@ -76,15 +77,14 @@
  * Robustness:
  *  - Promotion decisions are memoized per session id for this process; the
  *    durable event scan runs once per session per process, then O(1).
- *  - Subagents (delegationDepth > 0) are always promoted (resident catalog).
+ *  - Subagents (delegationDepth > 0) are always promoted (resident catalog)
+ *    unless `includeSubagents: true`.
  *  - A missing bootstrap tool degrades to the full catalog with a one-time
  *    warning instead of throwing, so a composition drift can never brick
  *    every request of a session.
- *  - The pre-step context filter degrades to "keep everything" on failure:
- *    a filter bug must never eat the user's context.
- *  - Invalid config (bad tool lists, unknown `promoteOn`, malformed
- *    `suppressedContextSources`, non-positive `bootstrapMaxTokens`) fails at
- *    apply time, i.e. at preset mount, where it is visible and fixable.
+ *  - Invalid config (bad tool lists, unknown `promoteOn`, malformed flags,
+ *    non-positive `bootstrapMaxTokens`) fails at apply time, i.e. at preset
+ *    mount, where it is visible and fixable.
  */
 
 import { createEpochPromotion } from './compaction-epoch.mjs'
@@ -94,14 +94,11 @@ export const name = 'anchored-tool-bootstrap'
 
 /**
  * Deliberately NO inject list: the listeners only touch services at event
- * time. Applying without an inject — combined with this row being FIRST in
- * agent.cordis.yml — registers the plugin before dsh-agent-instructions and
- * dsh-tool-skill, and waterfall after-next transforms apply in reverse
- * registration order, so the first-request strip below is the LAST transform.
- * With an inject here those plugins register first and re-inject their
- * messages after the strip. The pre-step listener additionally registers with
- * `prepend: true` so the strip stays the outermost transform even against
- * host-plane listeners and future row reordering.
+ * time. Keep this row right AFTER the context-gate row in agent.cordis.yml:
+ * waterfall after-next transforms apply in reverse registration order, so the
+ * tool filter here must register before any plugin that touches the same
+ * assembly. The optional budget listener registers with `prepend: true` so a
+ * later listener can never override the first-round cap after we set it.
  */
 export const inject = []
 
@@ -113,15 +110,16 @@ const PROMOTE_EVENTS = {
 }
 
 /** Every config key this plugin accepts — anything else is a typo. */
-const ALLOWED_KEYS = new Set(['bootstrapTools', 'promoteOn', 'bootstrapMaxTokens', 'suppressedContextSources', 'compactionTools'])
+const ALLOWED_KEYS = new Set(['bootstrapTools', 'promoteOn', 'bootstrapMaxTokens', 'compactionTools', 'includeSubagents'])
 
-/**
- * Context sources stripped from the first request by default. Both are
- * automatic `agent/pre-step` injections: the available-skills reminder
- * (`skill-catalog`) and the AGENTS.md/CLAUDE.md workspace digest
- * (`agent-instructions`). True Minimal mounts neither plugin.
- */
-const DEFAULT_SUPPRESSED_SOURCES = ['skill-catalog', 'agent-instructions']
+/** Validate an optional boolean flag with a default. */
+function booleanOption(value, field, fallback) {
+  if (value === undefined) return fallback
+  if (typeof value !== 'boolean') {
+    throw new TypeError(`${name}: ${field} must be a boolean`)
+  }
+  return value
+}
 
 /**
  * The default first-request catalog: the OFFICIAL Minimal preset's exact tool
@@ -152,19 +150,6 @@ function parsePromoteOn(value) {
   throw new TypeError(`${name}: promoteOn must be one of "tool-call", "assistant-message", "either"; got ${JSON.stringify(value)}`)
 }
 
-/**
- * Validate the suppressed context sources. Unlike the bootstrap tool lists,
- * an explicitly empty array is meaningful: it disables the context filter
- * while keeping the tool bootstrap.
- */
-function sourceList(value, field, fallback) {
-  if (value === undefined) return new Set(fallback)
-  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || item.length === 0)) {
-    throw new TypeError(`${name}: ${field} must be an array of non-empty strings`)
-  }
-  return new Set(value)
-}
-
 /**
  * Validate the optional first-request output cap. `undefined` means NO cap:
  * the Minimal tool schema anchors at the adapter-default maxTokens, and the
@@ -194,13 +179,13 @@ export function apply(ctx, config) {
   const bootstrapTools = stringList(source.bootstrapTools, 'bootstrapTools')
   const promoteEvents = parsePromoteOn(source.promoteOn)
   const bootstrapMaxTokens = optionalPositiveInt(source.bootstrapMaxTokens, 'bootstrapMaxTokens')
-  const suppressedSources = sourceList(source.suppressedContextSources, 'suppressedContextSources', DEFAULT_SUPPRESSED_SOURCES)
+  const includeSubagents = booleanOption(source.includeSubagents, 'includeSubagents', false)
   // Core work set exposed after a compaction, before re-promotion. Empty
   // means "no compaction recovery catalog": the session stays on the
   // bootstrap pair until a new promotion signal.
   const compactionTools = stringListOrEmpty(source.compactionTools, 'compactionTools')
 
-  const promotion = createEpochPromotion(promoteEvents)
+  const promotion = createEpochPromotion(promoteEvents, { includeSubagents })
   ctx.on('session/event', (session, event) => promotion.observe(session, event))
 
   let warned = false
@@ -270,7 +255,9 @@ export function apply(ctx, config) {
         return keepTools(assembled, keep, false)
       }
       // Controlled phase: the bootstrap pair; after a compaction, plus the
-      // compaction work set so mid-task work can continue.
+      // compaction work set so mid-task work can continue. Context control is
+      // NOT here: the companion `context-gate` plugin owns it (see the header
+      // note), so this filter touches only the tool catalog.
       const { boundary } = status
       const keep = new Set(bootstrapTools)
       if (boundary >= 0) for (const toolName of compactionTools) keep.add(toolName)
@@ -311,28 +298,4 @@ export function apply(ctx, config) {
       }
     }, { prepend: true })
   }
-
-  // Strip first-step injected reminders (skill catalog, AGENTS.md) during
-  // bootstrap. Because this listener is the first registered (see the inject
-  // note, the row order in agent.cordis.yml, and `prepend` below), the strip
-  // is the final waterfall transform and actually removes what later
-  // listeners inject.
-  ctx.on('agent/pre-step', async ({ agent }, next) => {
-    // Downstream errors propagate untouched; only this filter's own logic is guarded.
-    const decision = await next()
-    if (decision.kind === 'reject') return decision
-    try {
-      if (promotion.status(agent).promoted || suppressedSources.size === 0) return decision
-      if (!Array.isArray(decision.messages)) return decision
-      const kept = decision.messages.filter((message) => {
-        const kind = message?.source?.kind
-        return typeof kind !== 'string' || !suppressedSources.has(kind)
-      })
-      return kept.length === decision.messages.length ? decision : { ...decision, messages: kept }
-    } catch (error) {
-      // A filter bug must never eat context: degrade to keeping every message.
-      warnOnce(`${name}: pre-step context filter failed, keeping injected context: ${String((error && error.message) || error)}`)
-      return decision
-    }
-  }, { prepend: true })
 }

package/preset/turn-anchor.mjs

@@ -1,83 +0,0 @@
-/**
- * turn-anchor — prompt-tool 可选附加件：首轮独立锚定轮。
- *
- * 启用后，会话首个真实用户消息不直接发给模型：先把任务原样挪进
- * `agent.inbox` 的 `next-step`（持久事件），首步只发一条 anchorText 作为
- * 独立输入。模型先回应锚定句（实测首词稳定 "We need…"），driver 随后在同
- * 一轮内自动消费 next-step 中的真实任务继续执行——因此用户只发一次消息，
- * 但模型看到的首轮是锚定句。
- *
- * 状态从持久 session events 推导（resume/reload 安全）：
- *   - 已处理/已拆轮：events 含 source.plugin=turn-anchor 的消息，或会话已
- *     晋升（tool/call | assistant/message）；
- *   - 任务在 next-step inbox 中持久化，进程重启后由 driver 继续消费。
- * 失败兜底：inbox.append 抛错时原样返回决策，绝不吞掉用户任务。
- */
-
-/** Cordis plugin name used by loader diagnostics. */
-export const name = 'turn-anchor'
-
-/** No inject list: nothing to resolve, only event listeners. */
-export const inject = []
-
-/** 消息 id：优先 crypto.randomUUID，旧运行时回退到随机串。 */
-function newMessageId() {
-  return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
-    ? crypto.randomUUID()
-    : `turn-anchor-${Date.now()}-${Math.random().toString(36).slice(2)}`
-}
-
-export function apply(ctx, config) {
-  const anchorText = typeof config.anchorText === 'string' && config.anchorText.length > 0
-    ? config.anchorText
-    : undefined
-  if (anchorText === undefined) return
-
-  /** Sessions already handled in this process (memo; truth stays in events/inbox). */
-  const handled = new Set()
-
-  /** 是否已经拆过轮：锚定句消息是持久 user/message，兼容 data.message 嵌套形状。 */
-  const seenAnchor = (session) => session.events.some((event) => {
-    const payload = event.data && typeof event.data.message === 'object' && event.data.message !== null
-      ? event.data.message
-      : event.data
-    return payload?.source?.plugin === 'turn-anchor'
-  })
-
-  ctx.on('agent/pre-step', async ({ agent }, next) => {
-    const decision = await next()
-    if (decision.kind === 'reject') return decision
-    if (agent === undefined) return decision
-    const session = agent.session
-    if (session === undefined || handled.has(session.id)) return decision
-
-    const events = session.events
-    const promoted = events.some((event) => event.type === 'tool/call' || event.type === 'assistant/message')
-    if (promoted || seenAnchor(session)) {
-      handled.add(session.id)
-      return decision
-    }
-
-    // 首步里的真实用户消息（source.kind === 'user'）才是任务；插件消息原样保留。
-    const tasks = decision.messages.filter((message) => message?.source?.kind === 'user')
-    if (tasks.length === 0) return decision
-
-    // 任务挪进 next-step：driver 在本轮锚定步结束后自动 claim 并继续执行。
-    try {
-      for (const task of tasks) agent.inbox.append('next-step', task)
-    } catch {
-      // 入队失败（id 冲突/坏状态）→ 不拆轮，原样发送，绝不丢任务。
-      return decision
-    }
-
-    handled.add(session.id)
-    const anchor = {
-      id: newMessageId(),
-      role: 'user',
-      content: [{ type: 'text', text: anchorText }],
-      source: { kind: 'plugin', plugin: 'turn-anchor', form: 'notice', summary: 'turn-anchor 首轮独立锚定句' },
-    }
-    const kept = decision.messages.filter((message) => message?.source?.kind !== 'user')
-    return { ...decision, messages: [anchor, ...kept] }
-  })
-}