@goodandready/dsh-agent-loop-guard 0.2.2

package/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 GooDAnDReaDY

package/README.md

@@ -0,0 +1,46 @@
+# @goodandready/dsh-agent-loop-guard 0.2.2
+
+Host-only DeepSeek Harness bundle that prevents tool-call loops without changing DSH core.
+
+## Behaviour
+
+- treats a repeated call as a loop only when no successful result or state
+  change has appeared since the previous attempt;
+- permits legitimate iterations with the same arguments when the result or
+  explicit progress token changes;
+- allows read -> edit -> read -> edit when each step produces new evidence;
+- keeps Gitea/curl operations distinct by their complete operation arguments,
+  including HTTP method and endpoint, even when they share a base URL;
+- uses maxToolAttemptsPerTurn and maxProgressToolCallsPerTurn as budgets
+  since the last productive action, so productive work resets the counters;
+- after a loop or budget denial, enters answer-only mode for the current turn
+  and returns a normal DSH tool denial that requires a text answer; the next
+  turn resets that mode;
+- logs every LOOP_GUARD_STOP, LOOP_GUARD_LIMIT,
+  LOOP_GUARD_PROGRESS_LIMIT, LOOP_GUARD_DUPLICATE, and
+  LOOP_GUARD_REPEAT event with a redacted call summary and progress context;
+- preserves the assistant-output guard: it detects text-only loops across
+  block/step/turn boundaries and cancels with keepInbox: false; both repeated
+  individual lines and repeated multi-line blocks are covered.
+
+The repeat threshold remains controlled by maxCallsPerRepeatGroup (default 5),
+but it is evaluated against the current progress epoch rather than raw call
+count. A successful result is considered productive when its result fingerprint
+or explicit progress token differs from the last successful evidence. Failed or
+unknown results do not reset the guard.
+
+The legacy maxCallsPerToolPerTurn setting remains accepted as a compatibility
+alias. maxToolAttemptsPerTurn: 0 disables only the aggregate no-progress
+budget; repeat, stop, progress, and assistant-output protections remain active.
+Denials use the documented tools.guard API and remain normal structured DSH tool
+results, preserving session persistence.
+
+## Verification
+
+npm test
+npm run check
+
+
+## Assistant output settings
+
+The output guard uses maxRepeatedAssistantLines for single-line repetition and maxRepeatedAssistantBlocks (default 5) for identical multi-line blocks. maxAssistantBlockChars (default 16384) bounds the captured block fingerprint. Streaming chunks and their final assistant/message are deduplicated.

package/README.ru.md

@@ -0,0 +1,46 @@
+# @goodandready/dsh-agent-loop-guard 0.2.2
+
+Host-only DeepSeek Harness bundle that prevents tool-call loops without changing DSH core.
+
+## Behaviour
+
+- treats a repeated call as a loop only when no successful result or state
+  change has appeared since the previous attempt;
+- permits legitimate iterations with the same arguments when the result or
+  explicit progress token changes;
+- allows read -> edit -> read -> edit when each step produces new evidence;
+- keeps Gitea/curl operations distinct by their complete operation arguments,
+  including HTTP method and endpoint, even when they share a base URL;
+- uses maxToolAttemptsPerTurn and maxProgressToolCallsPerTurn as budgets
+  since the last productive action, so productive work resets the counters;
+- after a loop or budget denial, enters answer-only mode for the current turn
+  and returns a normal DSH tool denial that requires a text answer; the next
+  turn resets that mode;
+- logs every LOOP_GUARD_STOP, LOOP_GUARD_LIMIT,
+  LOOP_GUARD_PROGRESS_LIMIT, LOOP_GUARD_DUPLICATE, and
+  LOOP_GUARD_REPEAT event with a redacted call summary and progress context;
+- preserves the assistant-output guard: it detects text-only loops across
+  block/step/turn boundaries and cancels with keepInbox: false; both repeated
+  individual lines and repeated multi-line blocks are covered.
+
+The repeat threshold remains controlled by maxCallsPerRepeatGroup (default 5),
+but it is evaluated against the current progress epoch rather than raw call
+count. A successful result is considered productive when its result fingerprint
+or explicit progress token differs from the last successful evidence. Failed or
+unknown results do not reset the guard.
+
+The legacy maxCallsPerToolPerTurn setting remains accepted as a compatibility
+alias. maxToolAttemptsPerTurn: 0 disables only the aggregate no-progress
+budget; repeat, stop, progress, and assistant-output protections remain active.
+Denials use the documented tools.guard API and remain normal structured DSH tool
+results, preserving session persistence.
+
+## Verification
+
+npm test
+npm run check
+
+
+## Assistant output settings
+
+The output guard uses maxRepeatedAssistantLines for single-line repetition and maxRepeatedAssistantBlocks (default 5) for identical multi-line blocks. maxAssistantBlockChars (default 16384) bounds the captured block fingerprint. Streaming chunks and their final assistant/message are deduplicated.

package/README.zh.md

@@ -0,0 +1,46 @@
+# @goodandready/dsh-agent-loop-guard 0.2.2
+
+Host-only DeepSeek Harness bundle that prevents tool-call loops without changing DSH core.
+
+## Behaviour
+
+- treats a repeated call as a loop only when no successful result or state
+  change has appeared since the previous attempt;
+- permits legitimate iterations with the same arguments when the result or
+  explicit progress token changes;
+- allows read -> edit -> read -> edit when each step produces new evidence;
+- keeps Gitea/curl operations distinct by their complete operation arguments,
+  including HTTP method and endpoint, even when they share a base URL;
+- uses maxToolAttemptsPerTurn and maxProgressToolCallsPerTurn as budgets
+  since the last productive action, so productive work resets the counters;
+- after a loop or budget denial, enters answer-only mode for the current turn
+  and returns a normal DSH tool denial that requires a text answer; the next
+  turn resets that mode;
+- logs every LOOP_GUARD_STOP, LOOP_GUARD_LIMIT,
+  LOOP_GUARD_PROGRESS_LIMIT, LOOP_GUARD_DUPLICATE, and
+  LOOP_GUARD_REPEAT event with a redacted call summary and progress context;
+- preserves the assistant-output guard: it detects text-only loops across
+  block/step/turn boundaries and cancels with keepInbox: false; both repeated
+  individual lines and repeated multi-line blocks are covered.
+
+The repeat threshold remains controlled by maxCallsPerRepeatGroup (default 5),
+but it is evaluated against the current progress epoch rather than raw call
+count. A successful result is considered productive when its result fingerprint
+or explicit progress token differs from the last successful evidence. Failed or
+unknown results do not reset the guard.
+
+The legacy maxCallsPerToolPerTurn setting remains accepted as a compatibility
+alias. maxToolAttemptsPerTurn: 0 disables only the aggregate no-progress
+budget; repeat, stop, progress, and assistant-output protections remain active.
+Denials use the documented tools.guard API and remain normal structured DSH tool
+results, preserving session persistence.
+
+## Verification
+
+npm test
+npm run check
+
+
+## Assistant output settings
+
+The output guard uses maxRepeatedAssistantLines for single-line repetition and maxRepeatedAssistantBlocks (default 5) for identical multi-line blocks. maxAssistantBlockChars (default 16384) bounds the captured block fingerprint. Streaming chunks and their final assistant/message are deduplicated.

package/cordis.patch.yml

@@ -0,0 +1,15 @@
+# Host-only DSH bundle. No dsh.client entry exists because this package has no browser module.
+- insert:
+    - id: '@goodandready/dsh-agent-loop-guard'
+      name: '@goodandready/dsh-agent-loop-guard'
+      config:
+        maxToolAttemptsPerTurn: 64
+        maxProgressToolCallsPerTurn: 16
+        progressToolNames:
+          - todo_write
+        maxCallsPerRepeatGroup: 5
+        blockExactDuplicates: true
+        assistantOutputGuard: true
+        maxRepeatedAssistantLines: 5
+        maxRepeatedAssistantBlocks: 5
+        maxAssistantBlockChars: 16384

package/docs/architecture/baseline.md

@@ -0,0 +1,37 @@
+# Architecture baseline
+
+The plugin owns in-memory guard state only. Agent pre-step records turn and stop
+mode. The documented DSH tools.guard hook synchronously evaluates each tool
+attempt and returns either allow or a denial reason. Each accepted call enters a
+progress ledger with a full argument fingerprint, a normalized repeat
+fingerprint, and a pending/committed lifecycle. tools/result records the result
+fingerprint and optional progress token. A successful change from the last
+successful evidence advances a progress epoch, clears no-progress repeat
+groups, and resets contextual budgets. Failed or unknown results leave the
+no-progress counters intact.
+
+The independent assistant-output branch subscribes to DSH session/event. It
+tracks assistant/chunk text-delta events and assistant/message final content by
+session. The final-message path accepts only Array.isArray(message.content)
+text blocks and deduplicates messages already seen in the stream. After the
+configured number of identical complete normalized lines, and only when no tool
+call is active, it calls the public agent.cancel API with keepInbox: false.
+The streak survives block, step, and turn boundaries and latches until a new
+user message; tool calls reset the streak, and session-disposed events dispose
+the in-memory state.
+
+user message -> pre-step records turn -> model tool call -> tools.guard -> normalized DSH tool result -> model text response
+assistant/chunk or assistant/message -> output state -> repeated-line threshold -> agent.cancel(keepInbox: false)
+
+No DSH core, session log, client plugin, database, or external service changes.
+
+Ordinary loop-prone tools consume maxToolAttemptsPerTurn. Explicit progress/state
+tools (default todo_write) use a separate finite maxProgressToolCallsPerTurn
+budget, so required checklist writes remain available after ordinary research
+reaches its cap without creating an unlimited escape from the guard. Exact and
+normalized-repeat checks run before either budget and apply to both classes.
+
+
+## Assistant output loop detection
+
+The host-only guard keeps two independent bounded detectors. The existing detector counts consecutive normalized complete lines. The multi-line detector fingerprints each completed assistant block (at block-end or final assistant message), keeps the count across step and turn boundaries, and trips only after the configured number of identical blocks without an intervening user message or tool call. A streamed block and its final message are counted once.

package/docs/research/reuse-first.md

@@ -0,0 +1,17 @@
+# Reuse-first research
+
+Reviewed installed DSH components.
+
+- dsh-repeat-tool-reminder warns about repeat chains but does not enforce a bound.
+- dsh-approval-gate uses public tools.guard and demonstrates a fail-closed denial before tool execution.
+- agent/pre-step can reject a whole step, but DSH ends that turn as blocked and gives no model text response.
+
+GitHub search found no reusable external DSH anti-loop bundle on 2026-08-19. This project therefore adapts the documented DSH guard pattern with a small deterministic state module.
+
+The official DSH documentation describes plugins as the extension boundary and
+the Cordis primer documents session event handling and agent lifecycle APIs.
+The closest reusable external implementation found was opencode-auto-resume,
+which detects repeated model output in an OpenCode-specific runtime; it cannot
+be installed as a DSH bundle. This plugin therefore uses the documented DSH
+session/event and agents.get(...).cancel(..., { keepInbox: true }) APIs rather
+than patching DSH core.

package/docs/testing/test-plan.md

@@ -0,0 +1,21 @@
+# Test plan
+
+Unit coverage verifies canonical and normalized fingerprints, result/state
+progress epochs, productive same-argument iterations, unchanged-result
+no-progress loops, read/edit retries, contextual aggregate and progress
+budgets, distinct Gitea/curl endpoints, stop recovery on the next turn,
+redacted structured violation logs, failed-result handling, explicit progress
+tokens, malformed non-array user content, and turn reset.
+
+Separate assistant-output coverage verifies whitespace normalization, five-line
+threshold behavior, split streaming chunks, cross-block/step/turn persistence,
+assistant/message fallback with malformed-content safety, deduplication,
+tool-call suppression, user-message reset, configurable thresholds, multi-line
+block normalization, block repetition, and stream/final-message deduplication. The
+fixture is derived from the observed reinstall narration loop.
+
+Syntax checks validate ESM source files. Runtime smoke tests install the bundle
+in both the container and host/test profiles, replay productive and
+no-progress tool-result sequences through the public tools.guard lifecycle,
+and verify one structured denial plus an answer-only stop path. Assistant
+output smoke verifies one cancellation with keepInbox:false.

package/lib/assistant-output-state.js

@@ -0,0 +1,252 @@
+function sessionKey(session) {
+  if (typeof session === 'string' && session.length > 0) return session;
+  if (session !== null && typeof session === 'object') {
+    const id = session.id ?? session.session?.id ?? session.header?.id;
+    if (typeof id === 'string' && id.length > 0) return id;
+  }
+  return String(session ?? 'unknown');
+}
+
+export function normalizeAssistantLine(value) {
+  if (typeof value !== 'string') return '';
+  return value.replace(/\r/gu, '').replace(/\s+/gu, ' ').trim();
+}
+
+export function normalizeAssistantBlock(value) {
+  if (typeof value !== 'string') return '';
+  return value
+    .replace(/\r\n?/gu, '\n')
+    .split('\n')
+    .map((line) => normalizeAssistantLine(line))
+    .filter((line) => line !== '')
+    .join('\n');
+}
+
+export function positiveOutputLimit(value, fallback) {
+  return Number.isSafeInteger(value) && value >= 1 ? value : fallback;
+}
+
+export function assistantTextFromMessage(message) {
+  const content = message?.content;
+  if (!Array.isArray(content)) return '';
+  return content
+    .filter((block) => block !== null
+      && typeof block === 'object'
+      && block.type === 'text'
+      && typeof block.text === 'string')
+    .map((block) => block.text)
+    .join('');
+}
+
+export class AssistantOutputGuardState {
+  constructor(config = {}) {
+    this.maxRepeatedAssistantLines = positiveOutputLimit(config.maxRepeatedAssistantLines, 5);
+    this.maxRepeatedAssistantBlocks = positiveOutputLimit(config.maxRepeatedAssistantBlocks, 5);
+    this.maxAssistantBlockChars = positiveOutputLimit(config.maxAssistantBlockChars, 16_384);
+    this.bySession = new Map();
+  }
+
+  stateFor(session) {
+    const key = sessionKey(session);
+    let state = this.bySession.get(key);
+    if (state === undefined) {
+      state = {
+        turn: undefined,
+        step: undefined,
+        index: undefined,
+        pending: '',
+        streamedText: '',
+        streamedSkipAvailable: false,
+        blockText: '',
+        blockFinalized: false,
+        lastBlock: '',
+        blockRepeatCount: 0,
+        lastLine: '',
+        repeatCount: 0,
+        activeTools: new Set(),
+        triggered: false,
+        seenMessages: new Set(),
+      };
+      this.bySession.set(key, state);
+    }
+    return state;
+  }
+
+  beginBlock(session, turn, step, index = 0) {
+    const state = this.stateFor(session);
+    if (state.turn !== turn || state.step !== step || state.index !== index) {
+      state.turn = turn;
+      state.step = step;
+      state.index = index;
+      state.pending = '';
+      state.streamedText = '';
+      state.streamedSkipAvailable = false;
+      state.blockText = '';
+      state.blockFinalized = false;
+    }
+    return state;
+  }
+
+  resetStreak(session) {
+    const state = this.stateFor(session);
+    state.pending = '';
+    state.streamedText = '';
+    state.streamedSkipAvailable = false;
+    state.blockText = '';
+    state.blockFinalized = false;
+    state.lastBlock = '';
+    state.blockRepeatCount = 0;
+    state.lastLine = '';
+    state.repeatCount = 0;
+  }
+
+  resetForUser(session) {
+    const state = this.stateFor(session);
+    state.pending = '';
+    state.streamedText = '';
+    state.streamedSkipAvailable = false;
+    state.blockText = '';
+    state.blockFinalized = false;
+    state.lastBlock = '';
+    state.blockRepeatCount = 0;
+    state.lastLine = '';
+    state.repeatCount = 0;
+    state.triggered = false;
+    state.seenMessages.clear();
+  }
+
+  observeLine(session, line) {
+    const state = this.stateFor(session);
+    const normalized = normalizeAssistantLine(line);
+    if (normalized === '' || state.activeTools.size > 0 || state.triggered) return undefined;
+    if (normalized === state.lastLine) {
+      state.repeatCount += 1;
+    } else {
+      state.lastLine = normalized;
+      state.repeatCount = 1;
+    }
+    if (state.repeatCount >= this.maxRepeatedAssistantLines) {
+      state.triggered = true;
+      return {
+        count: state.repeatCount,
+        line: normalized,
+        reason: 'LOOP_GUARD_ASSISTANT_OUTPUT: repeated assistant text detected; generation cancelled and pending inbox cleared.',
+      };
+    }
+    return undefined;
+  }
+
+  observeText(session, { turn, step, index = 0, text } = {}) {
+    if (typeof text !== 'string' || text.length === 0) return undefined;
+    const state = this.beginBlock(session, turn, step, index);
+    if (state.activeTools.size > 0 || state.triggered) return undefined;
+    state.streamedText += text;
+    state.blockText += text;
+    if (state.blockText.length > this.maxAssistantBlockChars) {
+      state.blockText = state.blockText.slice(-this.maxAssistantBlockChars);
+    }
+    state.streamedSkipAvailable = true;
+    state.pending += text;
+    const lines = state.pending.split(/\n/gu);
+    state.pending = lines.pop() ?? '';
+    for (const line of lines) {
+      const hit = this.observeLine(session, line);
+      if (hit) return hit;
+    }
+    return undefined;
+  }
+
+  observeBlock(session, block) {
+    const state = this.stateFor(session);
+    const normalized = normalizeAssistantBlock(block);
+    if (normalized === '' || !normalized.includes('\n') || state.activeTools.size > 0 || state.triggered) return undefined;
+    if (normalized === state.lastBlock) {
+      state.blockRepeatCount += 1;
+    } else {
+      state.lastBlock = normalized;
+      state.blockRepeatCount = 1;
+    }
+    if (state.blockRepeatCount >= this.maxRepeatedAssistantBlocks) {
+      state.triggered = true;
+      return {
+        count: state.blockRepeatCount,
+        block: normalized,
+        reason: 'LOOP_GUARD_ASSISTANT_BLOCK: repeated assistant text block detected; generation cancelled and pending inbox cleared.',
+      };
+    }
+    return undefined;
+  }
+
+  finalizeBlock(session) {
+    const state = this.stateFor(session);
+    if (state.blockFinalized) return undefined;
+    state.blockFinalized = true;
+    return this.observeBlock(session, state.blockText);
+  }
+
+  observeMessage(session, { id, turn, step, index = 0, text } = {}) {
+    if (typeof text !== 'string' || text.length === 0) return undefined;
+    const state = this.beginBlock(session, turn, step, index);
+    const key = id === undefined || id === null
+      ? String(turn ?? 'u') + ':' + String(step ?? 's') + ':' + String(text.length)
+      : String(id);
+    if (state.seenMessages.has(key)) return undefined;
+    state.seenMessages.add(key);
+    const prior = state.streamedText;
+    if (prior === text && state.streamedSkipAvailable) {
+      state.streamedSkipAvailable = false;
+      return this.finalizeBlock(session);
+    }
+    const suffix = prior.length > 0 && prior !== text && text.startsWith(prior) ? text.slice(prior.length) : text;
+    const hit = this.observeText(session, { turn, step, index, text: suffix });
+    state.streamedText = text;
+    state.streamedSkipAvailable = false;
+    if (hit) return hit;
+    return this.finalizeBlock(session);
+  }
+
+  flushPending(session) {
+    const state = this.stateFor(session);
+    if (state.pending === '') return undefined;
+    const pending = state.pending;
+    state.pending = '';
+    return this.observeLine(session, pending);
+  }
+
+  markToolCall(session, callId) {
+    const state = this.stateFor(session);
+    if (typeof callId === 'string' && callId.length > 0) state.activeTools.add(callId);
+    this.resetStreak(session);
+  }
+
+  markToolResult(session, callId) {
+    const state = this.stateFor(session);
+    if (typeof callId === 'string' && callId.length > 0) state.activeTools.delete(callId);
+  }
+
+  hasActiveTool(session) {
+    return this.stateFor(session).activeTools.size > 0;
+  }
+
+  hasTriggered(session) {
+    return this.stateFor(session).triggered;
+  }
+
+  endBlock(session) {
+    const hit = this.flushPending(session);
+    if (hit) return hit;
+    return this.finalizeBlock(session);
+  }
+
+  endStep(session) {
+    return this.endBlock(session);
+  }
+
+  endTurn(session) {
+    return this.endBlock(session);
+  }
+
+  dispose(session) {
+    this.bySession.delete(sessionKey(session));
+  }
+}

package/lib/guard-state.js

@@ -0,0 +1,326 @@
+const STOP_REQUEST_PATTERN = /(?:\b(?:stop|halt|cancel|answer(?:\s+now)?)\b|останов(?:ись|ить)|прекрати|хватит|ответь|петл[яиюе])/iu;
+const SECRET_KEY_PATTERN = /(?:token|secret|password|authorization|api[-_]?key|cookie)/iu;
+
+function stableJson(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return '[' + value.map(stableJson).join(',') + ']';
+  return '{' + Object.keys(value).sort().map((key) => JSON.stringify(key) + ':' + stableJson(value[key])).join(',') + '}';
+}
+
+function normalizedJson(value) {
+  if (value === null || typeof value !== 'object') {
+    if (typeof value === 'string') return JSON.stringify(value.trim().replace(/\s+/gu, ' '));
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) return '[' + value.map(normalizedJson).join(',') + ']';
+  return '{' + Object.keys(value).sort().map((key) => JSON.stringify(key) + ':' + normalizedJson(value[key])).join(',') + '}';
+}
+
+function textFrom(value) {
+  if (!Array.isArray(value)) return '';
+  return value.map((block) => {
+    if (block === null || typeof block !== 'object') return '';
+    if (typeof block.text === 'string') return block.text;
+    if (Array.isArray(block.content)) return textFrom(block.content);
+    return '';
+  }).join('\n');
+}
+
+function safeLogValue(value, depth = 0) {
+  if (depth > 3) return '[depth-limit]';
+  if (typeof value === 'string') {
+    return value.replace(/((?:Bearer|token)\s+)[^\s'"]+/giu, '$1[redacted]')
+      .replace(/((?:token|secret|password|authorization|api[-_]?key)=)[^\s&]+/giu, '$1[redacted]')
+      .slice(0, 400);
+  }
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.slice(0, 20).map((item) => safeLogValue(item, depth + 1));
+  const output = {};
+  for (const [key, item] of Object.entries(value).slice(0, 40)) {
+    output[key] = SECRET_KEY_PATTERN.test(key) ? '[redacted]' : safeLogValue(item, depth + 1);
+  }
+  return output;
+}
+
+export function positiveInteger(value, fallback) {
+  return Number.isSafeInteger(value) && value >= 1 ? value : fallback;
+}
+
+export function nonNegativeInteger(value, fallback) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : fallback;
+}
+
+export function hasStopRequest(messages) {
+  if (!Array.isArray(messages)) return false;
+  return messages.some((message) => message?.source?.kind === 'user' && STOP_REQUEST_PATTERN.test(textFrom(message.content)));
+}
+
+export function callFingerprint(name, args) {
+  try { return String(name) + ':' + stableJson(args); }
+  catch { return String(name) + ':<unserializable>'; }
+}
+
+export function callRepeatFingerprint(name, args) {
+  try { return String(name) + ':' + normalizedJson(args); }
+  catch { return String(name) + ':<unserializable>'; }
+}
+
+export function resultFingerprint(value) {
+  try { return stableJson(value); }
+  catch { return '<unserializable-result>'; }
+}
+
+export function safeCallSummary(name, args) {
+  return {
+    tool: String(name),
+    arguments: safeLogValue(args),
+  };
+}
+
+function hasOwn(object, key) {
+  return object !== null && typeof object === 'object' && Object.prototype.hasOwnProperty.call(object, key);
+}
+
+function outcomeFromExecution(execution) {
+  const data = execution?.data;
+  const hasResult = hasOwn(execution, 'result') || hasOwn(execution, 'output')
+    || hasOwn(data, 'result') || hasOwn(data, 'output') || hasOwn(execution, 'error');
+  if (!hasResult) return { known: false, successful: false, resultFingerprint: '<unknown>', progressToken: '<unknown>' };
+  const value = execution?.result ?? execution?.output ?? data?.result ?? data?.output
+    ?? (hasOwn(execution, 'error') ? { error: execution.error } : undefined);
+  const failed = execution?.error !== undefined
+    || value?.isError === true
+    || value?.success === false
+    || value?.ok === false
+    || value?.error !== undefined;
+  const explicitProgress = execution?.progressToken ?? execution?.progress ?? execution?.stateVersion
+    ?? data?.progressToken ?? data?.progress ?? data?.stateVersion;
+  return {
+    known: true,
+    successful: !failed,
+    resultFingerprint: resultFingerprint(value),
+    progressToken: explicitProgress === undefined ? resultFingerprint(value) : resultFingerprint(explicitProgress),
+  };
+}
+
+export class LoopGuardState {
+  constructor(config = {}) {
+    const progressToolNames = Array.isArray(config.progressToolNames)
+      ? config.progressToolNames
+        .filter((name) => typeof name === 'string' && name.trim() !== '')
+        .map((name) => name.trim())
+      : ['todo_write'];
+    this.config = {
+      ...config,
+      maxToolAttemptsPerTurn: nonNegativeInteger(config.maxToolAttemptsPerTurn, 64),
+      maxProgressToolCallsPerTurn: positiveInteger(config.maxProgressToolCallsPerTurn, 16),
+      maxCallsPerRepeatGroup: positiveInteger(config.maxCallsPerRepeatGroup, 5),
+    };
+    this.onViolation = typeof config.onViolation === 'function' ? config.onViolation : undefined;
+    this.progressToolNames = new Set(progressToolNames);
+    this.byAgent = new Map();
+    this.objectKeys = new WeakMap();
+    this.nextObjectKey = 1;
+  }
+
+  agentKey(agent) {
+    if (agent !== null && typeof agent === 'object') {
+      const sessionId = agent.session?.id ?? agent.session?.header?.id ?? agent.id;
+      if (typeof sessionId === 'string' && sessionId.length > 0) return 'session:' + sessionId;
+      let key = this.objectKeys.get(agent);
+      if (key === undefined) {
+        key = 'object:' + this.nextObjectKey++;
+        this.objectKeys.set(agent, key);
+      }
+      return key;
+    }
+    return 'agent:' + String(agent ?? 'unknown');
+  }
+
+  emptyState(turn = undefined) {
+    return {
+      turn,
+      attemptsSinceProgress: 0,
+      progressAttemptsSinceProgress: 0,
+      calls: [],
+      nextCallKey: 1,
+      stopRequested: false,
+      answerOnly: false,
+      stopReason: '',
+      progressEpoch: 0,
+      repeatGroups: new Map(),
+      exactGroups: new Map(),
+      lastResults: new Map(),
+      lastProgress: undefined,
+      lastEvidence: undefined,
+    };
+  }
+
+  beginTurn(agent, turn, stopRequested) {
+    const key = this.agentKey(agent);
+    const prior = this.byAgent.get(key);
+    if (prior === undefined || prior.turn !== turn) {
+      const next = this.emptyState(turn);
+      next.stopRequested = Boolean(stopRequested);
+      this.byAgent.set(key, next);
+      return;
+    }
+    if (stopRequested) prior.stopRequested = true;
+  }
+
+  stateFor(agent) {
+    const key = this.agentKey(agent);
+    let state = this.byAgent.get(key);
+    if (state === undefined) {
+      state = this.emptyState();
+      this.byAgent.set(key, state);
+    }
+    return state;
+  }
+
+  findCall(state, callId) {
+    if (typeof callId === 'string' && callId.length > 0) {
+      const exact = [...state.calls].reverse().find((call) => call.id === callId && !call.released);
+      if (exact !== undefined) return exact;
+    }
+    return [...state.calls].reverse().find((call) => !call.released && !call.resultSeen);
+  }
+
+  decrementReservations(state, call) {
+    if (!call || !call.counted || call.committed) return;
+    state.attemptsSinceProgress = Math.max(0, state.attemptsSinceProgress - 1);
+    if (call.isProgressTool) state.progressAttemptsSinceProgress = Math.max(0, state.progressAttemptsSinceProgress - 1);
+  }
+
+  violation(state, agent, name, args, callId, code, detail) {
+    state.answerOnly = true;
+    state.stopReason = code + ': ' + detail;
+    const summary = safeCallSummary(name, args);
+    const event = {
+      code,
+      reason: detail,
+      callId: typeof callId === 'string' ? callId : undefined,
+      agent: this.agentKey(agent),
+      progressEpoch: state.progressEpoch,
+      attemptsSinceProgress: state.attemptsSinceProgress,
+      progressAttemptsSinceProgress: state.progressAttemptsSinceProgress,
+      lastProgress: state.lastProgress,
+      ...summary,
+    };
+    try { this.onViolation?.(event); } catch {}
+    return code + ': ' + detail
+      + ' No productive progress was observed; provide the final text answer now. The next turn resets this guard.';
+  }
+
+  denyReason(agent, name, args, callId) {
+    const state = this.stateFor(agent);
+    if (state.stopRequested) {
+      return this.violation(state, agent, name, args, callId, 'LOOP_GUARD_STOP', 'user requested stop; tools are disabled for this turn');
+    }
+    if (state.answerOnly) {
+      return this.violation(state, agent, name, args, callId, 'LOOP_GUARD_STOP', state.stopReason || 'previous guard violation requires a text answer');
+    }
+    const fingerprint = callFingerprint(name, args);
+    const repeatFingerprint = callRepeatFingerprint(name, args);
+    const repeatGroup = state.repeatGroups.get(repeatFingerprint);
+    const exactGroup = state.exactGroups.get(fingerprint);
+    const repeatCount = repeatGroup?.progressEpoch === state.progressEpoch ? repeatGroup.count : 0;
+    const exactCount = exactGroup?.progressEpoch === state.progressEpoch ? exactGroup.count : 0;
+    if (repeatCount >= this.config.maxCallsPerRepeatGroup) {
+      if (this.config.blockExactDuplicates && exactCount >= this.config.maxCallsPerRepeatGroup) {
+        return this.violation(state, agent, name, args, callId, 'LOOP_GUARD_DUPLICATE', 'identical tool call repeated without a new result or state change after ' + repeatCount + ' attempts');
+      }
+      return this.violation(state, agent, name, args, callId, 'LOOP_GUARD_REPEAT', 'near-identical tool call repeated without a new result or state change after ' + repeatCount + ' attempts');
+    }
+    const isProgressTool = this.progressToolNames.has(String(name));
+    if (isProgressTool) {
+      if (state.progressAttemptsSinceProgress >= this.config.maxProgressToolCallsPerTurn) {
+        return this.violation(state, agent, name, args, callId, 'LOOP_GUARD_PROGRESS_LIMIT', 'progress/state tool budget exhausted without productive progress');
+      }
+    } else if (this.config.maxToolAttemptsPerTurn > 0 && state.attemptsSinceProgress >= this.config.maxToolAttemptsPerTurn) {
+      return this.violation(state, agent, name, args, callId, 'LOOP_GUARD_LIMIT', 'tool budget exhausted without productive progress');
+    }
+    const id = typeof callId === 'string' && callId.length > 0 ? callId : 'anonymous-' + String(state.nextCallKey++);
+    const priorRepeat = state.repeatGroups.get(repeatFingerprint);
+    const priorExact = state.exactGroups.get(fingerprint);
+    state.repeatGroups.set(repeatFingerprint, {
+      count: (priorRepeat?.progressEpoch === state.progressEpoch ? priorRepeat.count : 0) + 1,
+      progressEpoch: state.progressEpoch,
+    });
+    state.exactGroups.set(fingerprint, {
+      count: (priorExact?.progressEpoch === state.progressEpoch ? priorExact.count : 0) + 1,
+      progressEpoch: state.progressEpoch,
+    });
+    const call = {
+      id,
+      fingerprint,
+      repeatFingerprint,
+      isProgressTool,
+      pending: true,
+      committed: false,
+      released: false,
+      counted: true,
+      resultSeen: false,
+    };
+    state.calls.push(call);
+    state.attemptsSinceProgress += 1;
+    if (isProgressTool) state.progressAttemptsSinceProgress += 1;
+    return undefined;
+  }
+
+  commitCall(agent, callId) {
+    const state = this.stateFor(agent);
+    const call = this.findCall(state, callId);
+    if (call !== undefined) {
+      call.pending = false;
+      call.committed = true;
+    }
+  }
+
+  recordResult(agent, execution = {}) {
+    const state = this.stateFor(agent);
+    const call = this.findCall(state, execution.callId);
+    if (call === undefined) return { known: false, productive: false };
+    if (call.pending && !call.committed) {
+      call.released = true;
+      this.decrementReservations(state, call);
+      return { known: false, productive: false };
+    }
+    const outcome = outcomeFromExecution(execution);
+    call.pending = false;
+    call.committed = true;
+    call.resultSeen = true;
+    call.resultFingerprint = outcome.resultFingerprint;
+    call.progressToken = outcome.progressToken;
+    const prior = state.lastEvidence;
+    const productive = outcome.known && outcome.successful
+      && (prior === undefined
+        || prior.resultFingerprint !== outcome.resultFingerprint
+        || prior.progressToken !== outcome.progressToken);
+    call.productive = productive;
+    state.lastResults.set(call.repeatFingerprint, outcome);
+    if (productive) {
+      state.lastEvidence = outcome;
+      state.progressEpoch += 1;
+      state.attemptsSinceProgress = 0;
+      state.progressAttemptsSinceProgress = 0;
+      state.repeatGroups.clear();
+      state.exactGroups.clear();
+      state.lastProgress = {
+        callId: call.id,
+        tool: call.fingerprint.split(':', 1)[0],
+        resultFingerprint: outcome.resultFingerprint,
+        progressToken: outcome.progressToken,
+      };
+    }
+    return { known: outcome.known, productive };
+  }
+
+  releaseCall(agent, callId) {
+    const state = this.stateFor(agent);
+    const call = this.findCall(state, callId);
+    if (call === undefined) return;
+    call.released = true;
+    this.decrementReservations(state, call);
+  }
+}

package/lib/index.js

@@ -0,0 +1,176 @@
+import Schema from '@deepseek-ai/schemastery';
+import {
+  LoopGuardState,
+  hasStopRequest,
+  nonNegativeInteger,
+  positiveInteger,
+} from './guard-state.js';
+import { AssistantOutputGuardState, assistantTextFromMessage } from './assistant-output-state.js';
+
+export const name = '@goodandready/dsh-agent-loop-guard';
+export const inject = ['tools', 'agents', 'sessions'];
+
+export const Config = Schema.object({
+  maxToolAttemptsPerTurn: Schema.number().min(0).default(64),
+  maxProgressToolCallsPerTurn: Schema.number().min(1).default(16),
+  progressToolNames: Schema.array(Schema.string()).default(['todo_write']),
+  maxCallsPerRepeatGroup: Schema.number().min(1).default(5),
+  maxCallsPerToolPerTurn: Schema.number().min(1).default(5),
+  blockExactDuplicates: Schema.boolean().default(true),
+  assistantOutputGuard: Schema.boolean().default(true),
+  maxRepeatedAssistantLines: Schema.number().min(1).default(5),
+  maxRepeatedAssistantBlocks: Schema.number().min(1).default(5),
+  maxAssistantBlockChars: Schema.number().min(256).default(16_384),
+});
+
+function callIdFromEvent(event) {
+  return event?.data?.callId
+    ?? event?.data?.message?.source?.callId
+    ?? event?.data?.message?.source?.toolCallId;
+}
+
+function cancelForOutputLoop(ctx, session, reason) {
+  let agent;
+  try {
+    agent = ctx.agents?.get?.(session.id);
+  } catch (error) {
+    ctx.logger?.warn?.('dsh-agent-loop-guard: failed to resolve agent for output guard: ' + (error instanceof Error ? error.message : String(error)));
+    return;
+  }
+  if (agent === undefined || typeof agent.cancel !== 'function') return;
+  try {
+    agent.cancel(new Error(reason), { keepInbox: false });
+  } catch (error) {
+    ctx.logger?.warn?.('dsh-agent-loop-guard: output-loop cancellation threw: ' + (error instanceof Error ? error.message : String(error)));
+  }
+}
+
+function cancelOnOutputHit(ctx, session, assistantState, hit) {
+  if (!hit || assistantState.hasActiveTool(session.id)) return;
+  const code = String(hit.reason).split(':', 1)[0];
+  const event = {
+    code,
+    reason: hit.reason,
+    session: session.id,
+    count: hit.count,
+    outputKind: hit.block === undefined ? 'line' : 'block',
+    blockChars: typeof hit.block === 'string' ? hit.block.length : undefined,
+  };
+  try {
+    ctx.logger?.warn?.('dsh-agent-loop-guard: ' + JSON.stringify(event));
+  } catch (error) {
+    ctx.logger?.warn?.('dsh-agent-loop-guard: ' + code + ' session=' + session.id);
+  }
+  cancelForOutputLoop(ctx, session, hit.reason);
+}
+
+function logGuardViolation(ctx, event) {
+  const safeEvent = {
+    code: event.code,
+    reason: event.reason,
+    callId: event.callId,
+    agent: event.agent,
+    tool: event.tool,
+    arguments: event.arguments,
+    progressEpoch: event.progressEpoch,
+    attemptsSinceProgress: event.attemptsSinceProgress,
+    progressAttemptsSinceProgress: event.progressAttemptsSinceProgress,
+    lastProgress: event.lastProgress,
+  };
+  try {
+    ctx.logger?.warn?.('dsh-agent-loop-guard: ' + event.code + ' ' + JSON.stringify(safeEvent));
+  } catch (error) {
+    ctx.logger?.warn?.('dsh-agent-loop-guard: ' + event.code + ' (structured log unavailable)');
+  }
+}
+
+export function apply(ctx, config = {}) {
+  const raw = Config(config) ?? {};
+  const maxCallsPerRepeatGroup = positiveInteger(raw.maxCallsPerRepeatGroup ?? raw.maxCallsPerToolPerTurn, 5);
+  const state = new LoopGuardState({
+    ...raw,
+    maxToolAttemptsPerTurn: nonNegativeInteger(raw.maxToolAttemptsPerTurn, 64),
+    maxProgressToolCallsPerTurn: positiveInteger(raw.maxProgressToolCallsPerTurn, 16),
+    maxCallsPerRepeatGroup,
+    onViolation: (event) => logGuardViolation(ctx, event),
+  });
+  const assistantState = new AssistantOutputGuardState({
+    maxRepeatedAssistantLines: positiveInteger(raw.maxRepeatedAssistantLines, 5),
+    maxRepeatedAssistantBlocks: positiveInteger(raw.maxRepeatedAssistantBlocks, 5),
+    maxAssistantBlockChars: positiveInteger(raw.maxAssistantBlockChars, 16_384),
+  });
+
+  ctx.on('agent/pre-step', async ({ agent, turn, messages, signal }, next) => {
+    const decision = await next();
+    if (decision.kind === 'reject' || signal.aborted) return decision;
+    state.beginTurn(agent, turn, hasStopRequest(messages));
+    return decision;
+  });
+
+  ctx.on('tools/execute', async (execution, next) => {
+    state.commitCall(execution.agent, execution.callId);
+    return next();
+  });
+
+  ctx.on('tools/result', (execution) => {
+    state.recordResult(execution.agent, execution);
+  });
+
+  if (raw.assistantOutputGuard !== false) {
+    ctx.on('session/event', (session, event) => {
+      if (event.type === 'assistant/chunk') {
+        const chunk = event.data?.chunk;
+        if (chunk?.type === 'text-delta') {
+          const hit = assistantState.observeText(session.id, {
+            turn: event.data?.turn,
+            step: event.data?.step,
+            index: chunk.index,
+            text: chunk.text,
+          });
+          cancelOnOutputHit(ctx, session, assistantState, hit);
+        } else if (chunk?.type === 'block-end') {
+          const hit = assistantState.endBlock(session.id);
+          cancelOnOutputHit(ctx, session, assistantState, hit);
+        }
+        return;
+      }
+      if (event.type === 'assistant/message') {
+        const message = event.data?.message;
+        const hit = assistantState.observeMessage(session.id, {
+          id: message?.id ?? event.seq,
+          turn: event.data?.turn,
+          step: event.data?.step,
+          index: message?.index ?? 0,
+          text: assistantTextFromMessage(message),
+        });
+        cancelOnOutputHit(ctx, session, assistantState, hit);
+        return;
+      }
+      if (event.type === 'user/message') {
+        assistantState.resetForUser(session.id);
+        return;
+      }
+      if (event.type === 'tool/call') {
+        assistantState.markToolCall(session.id, callIdFromEvent(event));
+        return;
+      }
+      if (event.type === 'tool/result') {
+        assistantState.markToolResult(session.id, callIdFromEvent(event));
+        return;
+      }
+      if (event.type === 'step/end') {
+        const hit = assistantState.endStep(session.id);
+        cancelOnOutputHit(ctx, session, assistantState, hit);
+        return;
+      }
+      if (event.type === 'turn/end') {
+        const hit = assistantState.endTurn(session.id);
+        cancelOnOutputHit(ctx, session, assistantState, hit);
+        return;
+      }
+    });
+    ctx.on('session/disposed', (session) => assistantState.dispose(session.id));
+  }
+
+  return ctx.tools.guard((execution) => state.denyReason(execution.agent, execution.name, execution.arguments, execution.callId));
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@goodandready/dsh-agent-loop-guard",
+  "version": "0.2.2",
+  "description": "Fail-closed runtime tool-call loop guard for DeepSeek Harness.",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "README.ru.md",
+    "README.zh.md",
+    "docs",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check lib/index.js && node --check lib/guard-state.js && node --check lib/assistant-output-state.js"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GooDAnDReaDY/dsh-agent-loop-guard.git"
+  },
+  "homepage": "https://github.com/GooDAnDReaDY/dsh-agent-loop-guard",
+  "bugs": {
+    "url": "https://github.com/GooDAnDReaDY/dsh-agent-loop-guard/issues"
+  }
+}