dsh-loop-continue 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yunxiyang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# dsh-loop-continue
+
+Continue a DeepSeek Harness agent turn when the model only *narrated* its next
+action and forgot the tool call.
+
+The agent loop closes a turn as `completed` the moment a step emits text and no
+tool call. A model that writes "now I will re-apply the change" and stops looks
+finished to the loop, even though the work is half done.
+
+This plugin listens on `agent/turn-stopping`, replays the current turn's own
+session log, and only asks a judge model one strict `true`/`false` question
+when the shape matches that failure mode. `true` steers the same turn to run one
+more step; `false` (or an unparseable answer) lets the turn close.
+
+## Config
+
+| field            | default | meaning                                        |
+|------------------|---------|------------------------------------------------|
+| `maxContinuations` | 10    | hard cap on steering per turn (no infinite loop) |
+| `maxSteps`       | 10      | newest steps shown to the judge                |
+| `maxTailChars`   | 2000    | cap on the trailing assistant text             |
+| `judgeProvider`  | null    | override provider; null = follow session route |
+| `judgeModel`     | null    | override model; null = follow session route    |
+| `judgeMaxTokens` | 64      | judge output cap                               |
+| `judgeTemperature` | 0     | judge sampling temperature                     |
+| `steerText`      | built-in | message that resumes the turn                |
+| `debug`          | false   | log every evaluation                          |
+
+## Deterministic gates
+
+No model call runs unless the turn *both*:
+
+1. ended on a text-only step (no tool call), and
+2. called at least one tool earlier (so a plain one-shot answer is untouched).
+
+This keeps the extra judge call off ordinary finished turns and only spends it
+where the model plausibly dropped a pending action.

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# dsh bundle patch: inserts this plugin into a profile's layer stack.
+# Plain insert only (id + name), so hot-mount can activate it live.
+# Config lives in the profile's own cordis.patch.yml (or Settings UI).
+- insert:
+    - id: loop-continue
+      name: 'dsh-loop-continue'

package/lib/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Continue an agent turn when the model only narrated its next action instead
+ * of calling a tool.
+ *
+ * @module dsh-loop-continue
+ */
+
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name: 'loop-continue'
+
+/** The services this plugin reads from its Cordis context. */
+export declare const inject: ['llm']
+
+/** Resolved plugin policy; every field has a default, so all are optional. */
+export interface Config {
+  /** Hard cap on steering per turn (no infinite loop). */
+  maxContinuations?: number
+  /** Newest steps shown to the judge. */
+  maxSteps?: number
+  /** Cap on the trailing assistant text handed to the judge. */
+  maxTailChars?: number
+  /** Override provider; null = follow the session route. */
+  judgeProvider?: string | null
+  /** Override model; null = follow the session route. */
+  judgeModel?: string | null
+  /** Judge output cap. */
+  judgeMaxTokens?: number
+  /** Judge sampling temperature. */
+  judgeTemperature?: number
+  /** Message that resumes a steered turn. */
+  steerText?: string
+  /** Emit a diagnostic line for every hook evaluation. */
+  debug?: boolean
+}
+
+/** Reconstructed facts about one step of a turn. */
+export interface StepSummary {
+  step: number
+  tools: string[]
+  text: string
+}
+
+/** Deterministic facts pulled from one turn's own log entries. */
+export interface TurnSummary {
+  steps: StepSummary[]
+  text: string
+  userRequest: string
+  truncated: boolean
+}
+
+/**
+ * Reconstruct what one turn actually did from its own log entries.
+ *
+ * @param events - full session event log snapshot.
+ * @param turn - turn whose steps should be summarized.
+ * @param maxSteps - how many trailing steps to include.
+ */
+export declare function summarizeTurn(events: unknown[], turn: number, maxSteps: number): TurnSummary
+
+/**
+ * Decide whether one turn's log looks like an unfinished, silently-abandoned
+ * narration, before spending an LLM judge call.
+ */
+export declare function looksUnfinished(summary: TurnSummary): boolean
+
+/** Render the deterministic step summary as compact plain text. */
+export declare function renderSummary(summary: TurnSummary, maxTailChars: number): string
+
+/**
+ * Parse a strict boolean verdict; anything not clearly `true` counts as false.
+ */
+export declare function parseVerdict(text: string): boolean
+
+/** Register the turn-stopping guard on a Cordis context. */
+export declare function apply(ctx: unknown, config: Config): void

package/lib/index.js

@@ -0,0 +1,331 @@
+/**
+ * Continue an agent turn when the model only narrated its next action instead
+ * of calling a tool.
+ *
+ * The agent loop ends a turn as `completed` whenever a step produces text but
+ * no tool call (packages/core/agent-loop/src/agent.ts). A model that announces
+ * "now I will re-apply the change" and forgets the actual call therefore looks
+ * finished, and the turn closes mid-task.
+ *
+ * This plugin listens on `agent/turn-stopping`, reads this turn's own session
+ * log, and only when the shape matches that failure mode asks a model one
+ * yes/no question. A `true` answer steers, which keeps the SAME turn open and
+ * runs one more step.
+ *
+ * @module dsh-loop-continue
+ */
+
+import z from '@deepseek-ai/schemastery'
+import { BlockAssembler, createUserMessage } from '@deepseek-ai/dsh-llm'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'loop-continue'
+
+/** The hook, LLM service, and session projections this plugin reads. */
+export const inject = ['llm']
+
+/** Where a steering message claims to come from. */
+const PLUGIN_SOURCE = { kind: 'plugin', plugin: name }
+
+/** How many extra steps one turn may buy, across all of its stopping boundaries. */
+const DEFAULT_MAX_CONTINUATIONS = 10
+
+/** How many most-recent steps of the current turn the summary shows. */
+const DEFAULT_MAX_STEPS = 10
+
+/** Cap on the trailing assistant text handed to the judge. */
+const DEFAULT_MAX_TAIL_CHARS = 2000
+
+export const Config = z.object({
+  maxContinuations: z.number().step(1).min(0).default(DEFAULT_MAX_CONTINUATIONS),
+  maxSteps: z.number().step(1).min(1).default(DEFAULT_MAX_STEPS),
+  maxTailChars: z.number().step(1).min(1).default(DEFAULT_MAX_TAIL_CHARS),
+  judgeProvider: z.union([z.string(), z.const(null)]),
+  judgeModel: z.union([z.string(), z.const(null)]),
+  judgeMaxTokens: z.number().step(1).min(1).default(64),
+  judgeTemperature: z.number().default(0),
+  /** Steer text sent back to the model; the model then runs one more step. */
+  steerText: z.string().default(
+    'You described an action but did not call any tool. Continue the task now: '
+    + 'call the tool for the action you just described. Do not narrate — emit the tool call.',
+  ),
+  /** Emit a diagnostic line for every hook evaluation. */
+  debug: z.boolean().default(false),
+})
+
+/**
+ * Read a session's immutable event log across host core versions.
+ *
+ * 0.1.1-rc.2 (DSH Desktop 2.0.3) exposes events as a `session.events` getter;
+ * 0.1.5-alpha.2 renamed it to `session.snapshotEvents()`. Calling the wrong
+ * one yields the "is not a function" failure, so probe both and use whichever
+ * the running host actually provides.
+ *
+ * @param session - the agent's live session.
+ * @returns a frozen event array, or an empty array when neither API exists.
+ */
+function readEvents(session) {
+  if (typeof session?.snapshotEvents === 'function') {
+    return session.snapshotEvents()
+  }
+  if (session && Array.isArray(session.events)) {
+    return session.events
+  }
+  return []
+}
+
+/**
+ * Reconstruct what actually happened in one turn from its own log entries.
+ *
+ * Every agent/session event carries `turn`, so the summary is filtered by the
+ * turn number the hook was handed. Nothing here is inferred from prose: a step
+ * shows a tool call only if an `assistant/message` in that step really carried
+ * a `tool-call` block.
+ *
+ * @param events - full session event log snapshot.
+ * @param turn - turn whose steps should be summarized.
+ * @param maxSteps - how many trailing steps to include.
+ * @returns per-step facts plus the trailing assistant text.
+ */
+export function summarizeTurn(events, turn, maxSteps) {
+  const steps = []
+  let current = null
+  let lastText = ''
+  let userRequest = ''
+
+  for (const event of events) {
+    const data = event.data
+    if (data?.turn !== turn) continue
+
+    switch (event.type) {
+      case 'step/start': {
+        current = { step: data.step, tools: [], text: '' }
+        steps.push(current)
+        break
+      }
+      case 'assistant/message': {
+        const blocks = data.message?.content ?? []
+        const text = blocks.filter(b => b.type === 'text').map(b => b.text).join('\n')
+        const tools = blocks.filter(b => b.type === 'tool-call').map(b => b.name)
+        if (current !== null) {
+          current.tools.push(...tools)
+          if (text) current.text = text
+        }
+        if (text) lastText = text
+        break
+      }
+      default:
+        break
+    }
+  }
+
+  // The user instruction that opened this turn is the nearest preceding
+  // human message; it anchors the judge's notion of "the task".
+  for (let i = events.length - 1; i >= 0; i -= 1) {
+    const event = events[i]
+    if (event.type !== 'user/message' || event.data?.turn > turn) continue
+    const source = event.data.source
+    if (source?.kind !== 'user') continue
+    userRequest = (event.data.content ?? [])
+      .filter(b => b.type === 'text').map(b => b.text).join('\n')
+    break
+  }
+
+  const window = steps.slice(-maxSteps)
+  return { steps: window, text: lastText, userRequest, truncated: steps.length > window.length }
+}
+
+/**
+ * Decide whether one turn's log looks like an unfinished, silently-abandoned
+ * narration.
+ *
+ * Deterministic gates run before any model call:
+ *  - the turn must have ended on a text-only step (no tool call),
+ *  - the turn must have called at least one tool earlier, which excludes a
+ *    plain question answered directly in one step,
+ *  - the trailing text must exist and be non-trivial.
+ *
+ * @param summary - facts produced by {@link summarizeTurn}.
+ * @returns whether the LLM judge is worth invoking.
+ */
+export function looksUnfinished(summary) {
+  const { steps, text } = summary
+  if (steps.length === 0) return false
+  const last = steps[steps.length - 1]
+  if (last.tools.length > 0) return false
+  const earlierTools = steps.slice(0, -1).some(s => s.tools.length > 0)
+  if (!earlierTools) return false
+  return text.trim().length > 0
+}
+
+/** Render the deterministic step summary as compact plain text. */
+export function renderSummary(summary, maxTailChars) {
+  const lines = summary.steps.map(s => {
+    const tools = s.tools.length > 0 ? s.tools.join(', ') : 'no tool call'
+    return `  step ${s.step}: ${tools}`
+  })
+  const tail = summary.text.length > maxTailChars
+    ? `${summary.text.slice(-maxTailChars)}`
+    : summary.text
+  const priorNote = summary.truncated
+    ? `  (showing only the last ${summary.steps.length} steps)\n`
+    : ''
+  return [
+    'Steps actually executed in this turn:',
+    ...lines,
+    priorNote.trimEnd(),
+    '',
+    'Trailing assistant message (text only, no tool call):',
+    tail,
+    '',
+    'The human request this turn is answering:',
+    summary.userRequest || '(unknown)',
+  ].filter(line => line !== '').join('\n')
+}
+
+/**
+ * Parse a strict boolean verdict. Anything that is not clearly true counts as
+ * false, so an unparseable answer can never extend a turn.
+ */
+export function parseVerdict(text) {
+  const normalized = text.trim().toLowerCase()
+  const first = normalized.match(/\b(true|false)\b/)?.[1]
+  return first === 'true'
+}
+
+/**
+ * Ask the judge model whether the trailing text promises work that no tool
+ * call performed.
+ *
+ * @param ctx - plugin context exposing `ctx.llm`.
+ * @param route - provider/model to call.
+ * @param summary - deterministic turn facts.
+ * @param config - resolved plugin policy.
+ * @param signal - the turn's abort signal.
+ * @returns whether the turn should continue.
+ */
+async function judge(ctx, route, summary, config, signal) {
+  const system = [
+    'You inspect one coding-agent turn that just ended.',
+    'A turn ends when the agent writes text and calls no tool.',
+    'Decide whether that trailing text states an action the agent still',
+    'intends to perform, or merely reports completed work.',
+    'A promise of future action ("now I will...", "next I will...") that no',
+    'tool call in the step list performed means the task is unfinished.',
+    'A finished report, a question to the human, or a final answer means the',
+    'task is finished.',
+    'Reply with exactly one word: true or false.',
+  ].join(' ')
+
+  const messages = [{
+    role: 'user',
+    content: [{ type: 'text', text: renderSummary(summary, config.maxTailChars) }],
+  }]
+
+  const assembler = new BlockAssembler()
+  for await (const chunk of ctx.llm.stream({
+    provider: route.provider,
+    model: route.model,
+    system,
+    messages,
+    maxTokens: config.judgeMaxTokens,
+    temperature: config.judgeTemperature,
+    signal,
+  })) {
+    assembler.push(chunk)
+  }
+
+  const text = assembler.blocks()
+    .filter(b => b.type === 'text').map(b => b.text).join('')
+  return parseVerdict(text)
+}
+
+/**
+ * Register the turn-stopping guard.
+ * @param ctx - plugin context.
+ * @param config - plugin policy.
+ */
+export function apply(ctx, config) {
+  const maxContinuations = config.maxContinuations ?? DEFAULT_MAX_CONTINUATIONS
+  const maxSteps = config.maxSteps ?? DEFAULT_MAX_STEPS
+  const maxTailChars = config.maxTailChars ?? DEFAULT_MAX_TAIL_CHARS
+  const resolved = {
+    ...config,
+    maxContinuations,
+    maxSteps,
+    maxTailChars,
+    judgeMaxTokens: config.judgeMaxTokens ?? 64,
+    judgeTemperature: config.judgeTemperature ?? 0,
+    steerText: config.steerText ?? (
+      'You described an action but did not call any tool. Continue the task now: '
+      + 'call the tool for the action you just described. Do not narrate — emit the tool call.'
+    ),
+    debug: config.debug ?? false,
+  }
+
+  ctx.logger?.info?.(`[${name}] loaded: maxContinuations=${resolved.maxContinuations} `
+    + `maxSteps=${resolved.maxSteps} judge=${resolved.judgeProvider ?? '<session-route>'}`
+    + `/${resolved.judgeModel ?? '<session-route>'} debug=${String(resolved.debug)}`)
+
+  /**
+   * Continuations already spent per turn. The turn number is stable while
+   * steering keeps the same turn open, so this is a hard per-turn budget; a
+   * new human message opens a new turn number and a fresh budget.
+   */
+  const spent = new Map()
+
+  ctx.on('agent/turn-stopping', async ({ agent, turn, signal }) => {
+    const used = spent.get(turn) ?? 0
+    if (used >= resolved.maxContinuations) {
+      // Keep the exhausted entry: the hook fires again after every extra step
+      // this turn buys, so deleting it here would hand the turn a fresh budget
+      // and make maxContinuations unbounded. turn/end clears it instead.
+      return
+    }
+
+    const summary = summarizeTurn(readEvents(agent.session), turn, resolved.maxSteps)
+    if (!looksUnfinished(summary)) return
+
+    const route = resolved.judgeProvider !== undefined && resolved.judgeModel !== undefined
+      ? { provider: resolved.judgeProvider, model: resolved.judgeModel }
+      : routeOf(agent)
+
+    let verdict = false
+    try {
+      verdict = await judge(ctx, route, summary, resolved, signal)
+    } catch (error) {
+      // The judge is advisory: a failure must never wedge the turn.
+      if (resolved.debug) {
+        ctx.logger?.warn?.(`[${name}] judge failed: ${String(error)}`)
+      }
+      return
+    }
+
+    if (resolved.debug) {
+      ctx.logger?.info?.(`[${name}] turn ${turn} verdict=${String(verdict)} spent=${used}`)
+    }
+    if (!verdict) {
+      return
+    }
+
+    spent.set(turn, used + 1)
+    agent.steer(createUserMessage({
+      content: [{ type: 'text', text: resolved.steerText }],
+      source: PLUGIN_SOURCE,
+    }))
+  })
+
+  /** Drop bookkeeping once a turn truly closes. */
+  ctx.on('session/event', (_session, event) => {
+    if (event.type === 'turn/end') spent.delete(event.data.turn)
+  })
+}
+
+/** Read the turn's effective provider/model from the session request header. */
+function routeOf(agent) {
+  const config = agent.session.requestHeader()?.config
+  if (config === undefined) {
+    throw new Error(`[${name}] no request header yet; set judgeProvider/judgeModel explicitly`)
+  }
+  return { provider: config.provider, model: config.model }
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "dsh-loop-continue",
+  "version": "0.1.0",
+  "description": "Continue a DeepSeek Harness agent turn when the model narrated but did not call a tool.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["lib/index.js", "lib/index.d.ts", "cordis.patch.yml", "README.md"],
+  "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-session": "^0.1.1-rc.2"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}