Foreword

In DSH development and operations scenarios, interactions with Hermes often involve asynchronous task dispatch. If invoked directly, issues such as delayed state synchronization or concurrency conflicts may easily occur. dsh-task-queue provides a queue hub that uses file-based state management (queue.json) to coordinate task dispatch, execution, and feedback between DSH and Hermes.

What It Is

This is a cached tiered task queue for DSH↔Hermes collaboration, maintained by nicecx. It treats queue.json as the single source of truth, uses a lease/claim model to manage the task lifecycle, and provides anti-starvation mechanisms and mutex locks to ensure orderly task scheduling.

Core Capabilities

  1. Single Source of Truth: queue.json is the only trusted source of task state; all operations are based on this file.
  2. Three-Level Priority Queue: Tasks are divided into three tiers: reset (restart), approve (approval), and review (review); the priority order is reset > approve > review.
  3. Lease/Claim Model: The consumer side (Hermes side) executes tasks by claiming them, avoiding duplicate processing.
  4. Anti-Starvation and Atomic Locks: Supports priority aging algorithms to prevent low-priority tasks from being blocked; combined with an atomic busy-mutex to ensure safety under high concurrency.
  5. Consumer Side: The Hermes-side cron scheduled tasks (monitoring gatekeeping) are responsible for dequeueing and execution.

Typical Usage

This plugin works with application-layer plugin protocols; the typical flow is as follows:

dsh-auto-approver（审批）──┐
dsh-design-review（评审）──┼──入队──▶ dsh-task-queue ──▶ 消费端 ──▶ Hermes
dsh-reset-handoff（重启）──┘
  1. Approval Flow: dsh-auto-approver puts requests into the approve tier. The approval channel uses a fast-lane synchronous direct call and shares the busy lock.
  2. Review Flow: dsh-design-review puts requests into the review tier. After the consumer dequeues a task, it writes to the single-slot request.json; after review by Hermes, routing is performed by sessionId.
  3. Restart Flow: dsh-reset-handoff puts requests into the reset tier (highest priority). After passing the gate, the task invokes reset_agent.py.

Shared Mechanisms

The plugin provides a set of shared mechanisms to ensure environment consistency:
* Mutex Lock: Shares the .hermes-busy file to serialize Hermes invocations and prevent concurrent conflicts.
* Single Numbering Source: Serves as the single numbering source for requestId, ensuring unique numbering in scenarios such as docs/ scanning.

Installation and Enablement

The plugin is released under the MIT license. Since no specific installation commands are provided, refer to the source repository for integration.

Notes

  1. Runtime Permissions: The plugin runs with the permissions of the current DSH process. Before deployment, review the source code logic and license.
  2. Fault-Tolerance Strategy: The plugin follows a fail-closed strategy; in exceptional cases, it prevents tasks from continuing to flow.
  3. Documentation Reference: For detailed collaboration contracts, refer to “2.5 Architecture Overview” (~/.dsh/DSH-HERMES-CONTRACT.md).