@n-dx/core 0.1.0

package/packages/hench/dist/queue/execution-queue.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Execution queue for hench task runs.
+ *
+ * When the configured concurrency limit is reached, new task execution
+ * requests are held in a FIFO queue with optional priority override.
+ * Higher-priority tasks are inserted ahead of lower-priority ones.
+ *
+ * The queue is designed for in-process use: a single ExecutionQueue
+ * instance manages concurrency within one hench process (e.g. loop
+ * mode, epic-by-epic, or the web dashboard's task runner).
+ *
+ * @module hench/queue/execution-queue
+ */
+/**
+ * Task priority levels, ordered from highest to lowest.
+ * Used for priority-based insertion into the FIFO queue.
+ */
+export type TaskPriority = "critical" | "high" | "medium" | "low";
+/** Normalize a string to a known priority, defaulting to "medium". */
+export declare function normalizePriority(value?: string): TaskPriority;
+/** A task waiting in the execution queue. */
+export interface QueueEntry {
+    /** Task ID from the PRD. */
+    taskId: string;
+    /** Resolved priority for queue ordering. */
+    priority: TaskPriority;
+    /** ISO timestamp when the task was enqueued. */
+    enqueuedAt: string;
+}
+/** Snapshot of queue state, suitable for API/CLI display. */
+export interface QueueStatus {
+    /** Maximum concurrent task executions allowed. */
+    maxConcurrent: number;
+    /** Number of tasks currently executing. */
+    activeCount: number;
+    /** Number of tasks waiting in the queue. */
+    queuedCount: number;
+    /** Whether the queue is accepting new tasks. */
+    accepting: boolean;
+    /** Ordered list of queued tasks (first = next to run). */
+    queued: Array<QueueEntry & {
+        position: number;
+    }>;
+}
+/**
+ * Bounded execution queue with FIFO scheduling and priority override.
+ *
+ * Callers {@link acquire} a slot before starting a task run and
+ * {@link release} it when the run completes (regardless of outcome).
+ * If the queue is full, `acquire` returns a Promise that resolves
+ * when a slot becomes available.
+ *
+ * @example
+ * ```ts
+ * const queue = new ExecutionQueue(3);
+ *
+ * await queue.acquire("task-123", "high");
+ * try {
+ *   await runOne(/* ... *\/);
+ * } finally {
+ *   queue.release();
+ * }
+ *
+ * console.log(queue.status());
+ * ```
+ */
+export declare class ExecutionQueue {
+    private readonly _maxConcurrent;
+    private _activeCount;
+    private _queue;
+    private _draining;
+    constructor(maxConcurrent: number);
+    /** Maximum concurrent task executions allowed. */
+    get maxConcurrent(): number;
+    /** Number of tasks currently executing. */
+    get active(): number;
+    /** Number of tasks waiting in the queue. */
+    get pending(): number;
+    /** Whether the queue is accepting new task requests. */
+    get accepting(): boolean;
+    /**
+     * Acquire an execution slot for a task.
+     *
+     * If a slot is available, resolves immediately. Otherwise the task
+     * is queued in FIFO order with priority override: tasks with a
+     * higher priority (lower rank) are inserted before tasks with a
+     * lower priority.
+     *
+     * @param taskId  PRD task identifier (for status display).
+     * @param priority  Task priority string (defaults to "medium").
+     * @returns Promise that resolves when a slot is available.
+     * @throws {Error} If the queue has been drained (shutdown).
+     */
+    acquire(taskId: string, priority?: string): Promise<void>;
+    /**
+     * Release an execution slot after a task run completes.
+     *
+     * If there are queued tasks, the next one is dequeued and its
+     * `acquire` promise is resolved so execution can begin.
+     *
+     * Must be called exactly once per successful `acquire`.
+     */
+    release(): void;
+    /**
+     * Return a snapshot of the current queue state.
+     *
+     * The returned object is a plain data structure (no functions or
+     * promises) suitable for JSON serialization and display.
+     */
+    status(): QueueStatus;
+    /**
+     * Drain the queue: reject all pending tasks and prevent new ones.
+     *
+     * Active tasks are not interrupted — they continue to completion.
+     * Only queued (waiting) tasks are rejected with a descriptive error.
+     *
+     * Call this on SIGINT / SIGTERM to clean up gracefully.
+     */
+    drain(): void;
+    /**
+     * Insert a queued entry in priority order.
+     *
+     * Within the same priority level, entries are appended (FIFO).
+     * Entries with a higher priority (lower rank number) are inserted
+     * before entries with a lower priority (higher rank number).
+     */
+    private _insertByPriority;
+}

package/packages/hench/dist/queue/execution-queue.js

@@ -0,0 +1,206 @@
+/**
+ * Execution queue for hench task runs.
+ *
+ * When the configured concurrency limit is reached, new task execution
+ * requests are held in a FIFO queue with optional priority override.
+ * Higher-priority tasks are inserted ahead of lower-priority ones.
+ *
+ * The queue is designed for in-process use: a single ExecutionQueue
+ * instance manages concurrency within one hench process (e.g. loop
+ * mode, epic-by-epic, or the web dashboard's task runner).
+ *
+ * @module hench/queue/execution-queue
+ */
+const PRIORITY_RANK = {
+    critical: 0,
+    high: 1,
+    medium: 2,
+    low: 3,
+};
+/** Normalize a string to a known priority, defaulting to "medium". */
+export function normalizePriority(value) {
+    if (value && value in PRIORITY_RANK)
+        return value;
+    return "medium";
+}
+// ---------------------------------------------------------------------------
+// ExecutionQueue
+// ---------------------------------------------------------------------------
+/**
+ * Bounded execution queue with FIFO scheduling and priority override.
+ *
+ * Callers {@link acquire} a slot before starting a task run and
+ * {@link release} it when the run completes (regardless of outcome).
+ * If the queue is full, `acquire` returns a Promise that resolves
+ * when a slot becomes available.
+ *
+ * @example
+ * ```ts
+ * const queue = new ExecutionQueue(3);
+ *
+ * await queue.acquire("task-123", "high");
+ * try {
+ *   await runOne(/* ... *\/);
+ * } finally {
+ *   queue.release();
+ * }
+ *
+ * console.log(queue.status());
+ * ```
+ */
+export class ExecutionQueue {
+    _maxConcurrent;
+    _activeCount = 0;
+    _queue = [];
+    _draining = false;
+    constructor(maxConcurrent) {
+        if (maxConcurrent < 1) {
+            throw new RangeError("ExecutionQueue maxConcurrent must be >= 1");
+        }
+        this._maxConcurrent = maxConcurrent;
+    }
+    // -----------------------------------------------------------------------
+    // Public getters
+    // -----------------------------------------------------------------------
+    /** Maximum concurrent task executions allowed. */
+    get maxConcurrent() {
+        return this._maxConcurrent;
+    }
+    /** Number of tasks currently executing. */
+    get active() {
+        return this._activeCount;
+    }
+    /** Number of tasks waiting in the queue. */
+    get pending() {
+        return this._queue.length;
+    }
+    /** Whether the queue is accepting new task requests. */
+    get accepting() {
+        return !this._draining;
+    }
+    // -----------------------------------------------------------------------
+    // acquire / release
+    // -----------------------------------------------------------------------
+    /**
+     * Acquire an execution slot for a task.
+     *
+     * If a slot is available, resolves immediately. Otherwise the task
+     * is queued in FIFO order with priority override: tasks with a
+     * higher priority (lower rank) are inserted before tasks with a
+     * lower priority.
+     *
+     * @param taskId  PRD task identifier (for status display).
+     * @param priority  Task priority string (defaults to "medium").
+     * @returns Promise that resolves when a slot is available.
+     * @throws {Error} If the queue has been drained (shutdown).
+     */
+    acquire(taskId, priority) {
+        if (this._draining) {
+            return Promise.reject(new Error("ExecutionQueue is draining; not accepting new tasks"));
+        }
+        // Slot available — grant immediately
+        if (this._activeCount < this._maxConcurrent) {
+            this._activeCount++;
+            return Promise.resolve();
+        }
+        // Queue the request
+        const resolved = normalizePriority(priority);
+        return new Promise((resolve, reject) => {
+            const entry = {
+                taskId,
+                priority: resolved,
+                enqueuedAt: new Date().toISOString(),
+                resolve,
+                reject,
+            };
+            this._insertByPriority(entry);
+        });
+    }
+    /**
+     * Release an execution slot after a task run completes.
+     *
+     * If there are queued tasks, the next one is dequeued and its
+     * `acquire` promise is resolved so execution can begin.
+     *
+     * Must be called exactly once per successful `acquire`.
+     */
+    release() {
+        if (this._activeCount <= 0) {
+            throw new Error("ExecutionQueue.release() called with no active slots");
+        }
+        // If there are queued tasks, hand the slot directly to the next one
+        if (this._queue.length > 0) {
+            const next = this._queue.shift();
+            // activeCount stays the same — slot transfers to the next task
+            next.resolve();
+        }
+        else {
+            this._activeCount--;
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Status
+    // -----------------------------------------------------------------------
+    /**
+     * Return a snapshot of the current queue state.
+     *
+     * The returned object is a plain data structure (no functions or
+     * promises) suitable for JSON serialization and display.
+     */
+    status() {
+        return {
+            maxConcurrent: this._maxConcurrent,
+            activeCount: this._activeCount,
+            queuedCount: this._queue.length,
+            accepting: !this._draining,
+            queued: this._queue.map((entry, idx) => ({
+                taskId: entry.taskId,
+                priority: entry.priority,
+                enqueuedAt: entry.enqueuedAt,
+                position: idx + 1,
+            })),
+        };
+    }
+    // -----------------------------------------------------------------------
+    // Drain (graceful shutdown)
+    // -----------------------------------------------------------------------
+    /**
+     * Drain the queue: reject all pending tasks and prevent new ones.
+     *
+     * Active tasks are not interrupted — they continue to completion.
+     * Only queued (waiting) tasks are rejected with a descriptive error.
+     *
+     * Call this on SIGINT / SIGTERM to clean up gracefully.
+     */
+    drain() {
+        this._draining = true;
+        const pending = this._queue.splice(0);
+        for (const entry of pending) {
+            entry.reject(new Error("ExecutionQueue drained: task cancelled before execution"));
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Internal helpers
+    // -----------------------------------------------------------------------
+    /**
+     * Insert a queued entry in priority order.
+     *
+     * Within the same priority level, entries are appended (FIFO).
+     * Entries with a higher priority (lower rank number) are inserted
+     * before entries with a lower priority (higher rank number).
+     */
+    _insertByPriority(entry) {
+        const rank = PRIORITY_RANK[entry.priority];
+        // Find the first position where the existing entry has a strictly
+        // lower priority (higher rank number) than the new entry.
+        let insertIdx = this._queue.length; // default: append at end
+        for (let i = 0; i < this._queue.length; i++) {
+            if (PRIORITY_RANK[this._queue[i].priority] > rank) {
+                insertIdx = i;
+                break;
+            }
+        }
+        this._queue.splice(insertIdx, 0, entry);
+    }
+}
+//# sourceMappingURL=execution-queue.js.map

package/packages/hench/dist/queue/execution-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-queue.js","sourceRoot":"","sources":["../../src/queue/execution-queue.ts"],"names":[],"mappings":"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"}

package/packages/hench/dist/queue/format.d.ts

@@ -0,0 +1,19 @@
+/**
+ * CLI formatting helpers for execution queue status display.
+ *
+ * @module hench/queue/format
+ */
+import type { QueueStatus } from "./execution-queue.js";
+/**
+ * Format queue status as human-readable CLI output lines.
+ *
+ * Returns an array of strings (one per line) suitable for printing
+ * to the terminal. Returns an empty array if the queue is idle
+ * (no active tasks, no pending tasks).
+ */
+export declare function formatQueueStatus(status: QueueStatus): string[];
+/**
+ * Format queue status as a JSON-serializable object.
+ * The returned object is the QueueStatus itself (already plain data).
+ */
+export declare function formatQueueStatusJson(status: QueueStatus): QueueStatus;

package/packages/hench/dist/queue/format.js

@@ -0,0 +1,52 @@
+/**
+ * CLI formatting helpers for execution queue status display.
+ *
+ * @module hench/queue/format
+ */
+/**
+ * Format queue status as human-readable CLI output lines.
+ *
+ * Returns an array of strings (one per line) suitable for printing
+ * to the terminal. Returns an empty array if the queue is idle
+ * (no active tasks, no pending tasks).
+ */
+export function formatQueueStatus(status) {
+    // Nothing to show if the queue is completely idle
+    if (status.activeCount === 0 && status.queuedCount === 0) {
+        return [];
+    }
+    const lines = [];
+    const utilization = `${status.activeCount}/${status.maxConcurrent}`;
+    lines.push(`Queue: ${utilization} slots active, ${status.queuedCount} queued`);
+    if (!status.accepting) {
+        lines.push("  ⚠ Queue is draining (not accepting new tasks)");
+    }
+    if (status.queued.length > 0) {
+        lines.push("  Pending:");
+        for (const entry of status.queued) {
+            const waitMs = Date.now() - new Date(entry.enqueuedAt).getTime();
+            const waitStr = formatWait(waitMs);
+            lines.push(`    ${entry.position}. [${entry.priority}] ${entry.taskId} (waiting ${waitStr})`);
+        }
+    }
+    return lines;
+}
+/**
+ * Format queue status as a JSON-serializable object.
+ * The returned object is the QueueStatus itself (already plain data).
+ */
+export function formatQueueStatusJson(status) {
+    return status;
+}
+/** Format a wait duration in ms as a human-readable string. */
+function formatWait(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    const seconds = Math.floor(ms / 1000);
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    const remaining = seconds % 60;
+    return `${minutes}m ${remaining}s`;
+}
+//# sourceMappingURL=format.js.map

package/packages/hench/dist/queue/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/queue/format.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAmB;IACnD,kDAAkD;IAClD,IAAI,MAAM,CAAC,WAAW,KAAK,CAAC,IAAI,MAAM,CAAC,WAAW,KAAK,CAAC,EAAE,CAAC;QACzD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,WAAW,GAAG,GAAG,MAAM,CAAC,WAAW,IAAI,MAAM,CAAC,aAAa,EAAE,CAAC;IAEpE,KAAK,CAAC,IAAI,CAAC,UAAU,WAAW,kBAAkB,MAAM,CAAC,WAAW,SAAS,CAAC,CAAC;IAE/E,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,iDAAiD,CAAC,CAAC;IAChE,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACzB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAClC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,OAAO,EAAE,CAAC;YACjE,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;YACnC,KAAK,CAAC,IAAI,CAAC,OAAO,KAAK,CAAC,QAAQ,MAAM,KAAK,CAAC,QAAQ,KAAK,KAAK,CAAC,MAAM,aAAa,OAAO,GAAG,CAAC,CAAC;QAChG,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAmB;IACvD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,+DAA+D;AAC/D,SAAS,UAAU,CAAC,EAAU;IAC5B,IAAI,EAAE,GAAG,IAAI;QAAE,OAAO,GAAG,EAAE,IAAI,CAAC;IAChC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;IACtC,IAAI,OAAO,GAAG,EAAE;QAAE,OAAO,GAAG,OAAO,GAAG,CAAC;IACvC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IACzC,MAAM,SAAS,GAAG,OAAO,GAAG,EAAE,CAAC;IAC/B,OAAO,GAAG,OAAO,KAAK,SAAS,GAAG,CAAC;AACrC,CAAC"}

package/packages/hench/dist/queue/index.d.ts

@@ -0,0 +1,5 @@
+export { ExecutionQueue, normalizePriority, } from "./execution-queue.js";
+export type { TaskPriority, QueueEntry, QueueStatus, } from "./execution-queue.js";
+export { formatQueueStatus, formatQueueStatusJson, } from "./format.js";
+export { resolveSchedulingPriority, extractPriorityFromTags, } from "./priority-scheduler.js";
+export type { TaskPriorityMetadata, } from "./priority-scheduler.js";

package/packages/hench/dist/queue/index.js

@@ -0,0 +1,4 @@
+export { ExecutionQueue, normalizePriority, } from "./execution-queue.js";
+export { formatQueueStatus, formatQueueStatusJson, } from "./format.js";
+export { resolveSchedulingPriority, extractPriorityFromTags, } from "./priority-scheduler.js";
+//# sourceMappingURL=index.js.map

package/packages/hench/dist/queue/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/queue/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAQ9B,OAAO,EACL,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,yBAAyB,CAAC"}

package/packages/hench/dist/queue/priority-scheduler.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Priority-based scheduling for hench task execution.
+ *
+ * Resolves the effective scheduling priority for a task by combining
+ * multiple priority signals with a clear precedence hierarchy:
+ *
+ *   CLI override  >  task explicit priority  >  tag-derived priority  >  default (medium)
+ *
+ * This module bridges the gap between PRD task metadata (where priority
+ * lives on the item itself or in tags) and the {@link ExecutionQueue}
+ * (which accepts a priority string for queue insertion ordering).
+ *
+ * @module hench/queue/priority-scheduler
+ */
+import type { TaskPriority } from "./execution-queue.js";
+/**
+ * Metadata used to resolve a task's scheduling priority.
+ *
+ * All fields are optional — absent fields are simply skipped
+ * in the resolution chain.
+ */
+export interface TaskPriorityMetadata {
+    /** The task's explicit priority field from the PRD item. */
+    taskPriority?: string;
+    /** The task's tags (may contain priority hints). */
+    tags?: string[];
+    /** CLI override (e.g. `--priority=critical`). Highest precedence. */
+    cliOverride?: string;
+}
+/**
+ * Extract a scheduling priority from task tags.
+ *
+ * Checks tags in order for:
+ * 1. `priority:<level>` prefix tags (e.g. `priority:high`)
+ * 2. Keyword tags (`urgent` → critical, `important` → high)
+ *
+ * Returns undefined if no priority signal is found in the tags.
+ */
+export declare function extractPriorityFromTags(tags?: string[]): TaskPriority | undefined;
+/**
+ * Resolve the effective scheduling priority for a task.
+ *
+ * Precedence (highest to lowest):
+ * 1. CLI override (`--priority` flag) — for urgent manual intervention
+ * 2. Task explicit priority (PRD item `priority` field)
+ * 3. Tag-derived priority (`priority:high`, `urgent`, `important` tags)
+ * 4. Default: `"medium"`
+ *
+ * Invalid or unrecognized values at any level are normalized to `"medium"`
+ * via {@link normalizePriority}.
+ *
+ * @example
+ * ```ts
+ * // CLI override wins
+ * resolveSchedulingPriority({
+ *   cliOverride: "critical",
+ *   taskPriority: "low",
+ *   tags: ["important"],
+ * }); // → "critical"
+ *
+ * // Task priority without override
+ * resolveSchedulingPriority({
+ *   taskPriority: "high",
+ *   tags: ["urgent"],
+ * }); // → "high"
+ *
+ * // Tag-derived priority as fallback
+ * resolveSchedulingPriority({
+ *   tags: ["urgent"],
+ * }); // → "critical"
+ * ```
+ */
+export declare function resolveSchedulingPriority(metadata: TaskPriorityMetadata): TaskPriority;

package/packages/hench/dist/queue/priority-scheduler.js

@@ -0,0 +1,119 @@
+/**
+ * Priority-based scheduling for hench task execution.
+ *
+ * Resolves the effective scheduling priority for a task by combining
+ * multiple priority signals with a clear precedence hierarchy:
+ *
+ *   CLI override  >  task explicit priority  >  tag-derived priority  >  default (medium)
+ *
+ * This module bridges the gap between PRD task metadata (where priority
+ * lives on the item itself or in tags) and the {@link ExecutionQueue}
+ * (which accepts a priority string for queue insertion ordering).
+ *
+ * @module hench/queue/priority-scheduler
+ */
+import { normalizePriority } from "./execution-queue.js";
+// ---------------------------------------------------------------------------
+// Priority tag patterns
+// ---------------------------------------------------------------------------
+/**
+ * Recognized tag prefixes/keywords that imply a scheduling priority.
+ *
+ * Two formats are supported:
+ * - Explicit: `priority:<level>` (e.g. `priority:high`)
+ * - Keyword: `urgent` → critical, `important` → high
+ */
+const TAG_PREFIX = "priority:";
+const KEYWORD_PRIORITY_MAP = {
+    urgent: "critical",
+    important: "high",
+};
+const VALID_PRIORITIES = new Set(["critical", "high", "medium", "low"]);
+// ---------------------------------------------------------------------------
+// Tag extraction
+// ---------------------------------------------------------------------------
+/**
+ * Extract a scheduling priority from task tags.
+ *
+ * Checks tags in order for:
+ * 1. `priority:<level>` prefix tags (e.g. `priority:high`)
+ * 2. Keyword tags (`urgent` → critical, `important` → high)
+ *
+ * Returns undefined if no priority signal is found in the tags.
+ */
+export function extractPriorityFromTags(tags) {
+    if (!tags || tags.length === 0)
+        return undefined;
+    // First pass: look for explicit `priority:<level>` tags
+    for (const tag of tags) {
+        const lower = tag.toLowerCase();
+        if (lower.startsWith(TAG_PREFIX)) {
+            const level = lower.slice(TAG_PREFIX.length);
+            if (VALID_PRIORITIES.has(level)) {
+                return level;
+            }
+        }
+    }
+    // Second pass: look for keyword tags
+    for (const tag of tags) {
+        const lower = tag.toLowerCase();
+        if (lower in KEYWORD_PRIORITY_MAP) {
+            return KEYWORD_PRIORITY_MAP[lower];
+        }
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Priority resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the effective scheduling priority for a task.
+ *
+ * Precedence (highest to lowest):
+ * 1. CLI override (`--priority` flag) — for urgent manual intervention
+ * 2. Task explicit priority (PRD item `priority` field)
+ * 3. Tag-derived priority (`priority:high`, `urgent`, `important` tags)
+ * 4. Default: `"medium"`
+ *
+ * Invalid or unrecognized values at any level are normalized to `"medium"`
+ * via {@link normalizePriority}.
+ *
+ * @example
+ * ```ts
+ * // CLI override wins
+ * resolveSchedulingPriority({
+ *   cliOverride: "critical",
+ *   taskPriority: "low",
+ *   tags: ["important"],
+ * }); // → "critical"
+ *
+ * // Task priority without override
+ * resolveSchedulingPriority({
+ *   taskPriority: "high",
+ *   tags: ["urgent"],
+ * }); // → "high"
+ *
+ * // Tag-derived priority as fallback
+ * resolveSchedulingPriority({
+ *   tags: ["urgent"],
+ * }); // → "critical"
+ * ```
+ */
+export function resolveSchedulingPriority(metadata) {
+    // 1. CLI override (highest precedence)
+    if (metadata.cliOverride != null) {
+        return normalizePriority(metadata.cliOverride);
+    }
+    // 2. Task explicit priority
+    if (metadata.taskPriority != null) {
+        return normalizePriority(metadata.taskPriority);
+    }
+    // 3. Tag-derived priority
+    const tagPriority = extractPriorityFromTags(metadata.tags);
+    if (tagPriority != null) {
+        return tagPriority;
+    }
+    // 4. Default
+    return "medium";
+}
+//# sourceMappingURL=priority-scheduler.js.map

package/packages/hench/dist/queue/priority-scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"priority-scheduler.js","sourceRoot":"","sources":["../../src/queue/priority-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAGzD,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,UAAU,GAAG,WAAW,CAAC;AAE/B,MAAM,oBAAoB,GAAiC;IACzD,MAAM,EAAE,UAAU;IAClB,SAAS,EAAE,MAAM;CAClB,CAAC;AAEF,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAS,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;AAqBhF,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAe;IACrD,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAEjD,wDAAwD;IACxD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;QAChC,IAAI,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YACjC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;YAC7C,IAAI,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBAChC,OAAO,KAAqB,CAAC;YAC/B,CAAC;QACH,CAAC;IACH,CAAC;IAED,qCAAqC;IACrC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;QAChC,IAAI,KAAK,IAAI,oBAAoB,EAAE,CAAC;YAClC,OAAO,oBAAoB,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,yBAAyB,CAAC,QAA8B;IACtE,uCAAuC;IACvC,IAAI,QAAQ,CAAC,WAAW,IAAI,IAAI,EAAE,CAAC;QACjC,OAAO,iBAAiB,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IACjD,CAAC;IAED,4BAA4B;IAC5B,IAAI,QAAQ,CAAC,YAAY,IAAI,IAAI,EAAE,CAAC;QAClC,OAAO,iBAAiB,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;IAClD,CAAC;IAED,0BAA0B;IAC1B,MAAM,WAAW,GAAG,uBAAuB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC3D,IAAI,WAAW,IAAI,IAAI,EAAE,CAAC;QACxB,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,aAAa;IACb,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/packages/hench/dist/schema/index.d.ts

@@ -0,0 +1,6 @@
+export { HENCH_SCHEMA_VERSION, DEFAULT_HENCH_CONFIG, } from "./v1.js";
+export type { GuardConfig, PolicyLimitsConfig, RetryConfig, HenchConfig, Provider, RunStatus, ToolCallRecord, TokenUsage, TurnTokenUsage, CommandRecord, TestRecord, PostRunTestRecord, SummaryCounts, RunSummaryData, RunMemoryStats, RunRecord, TaskBrief, TaskBriefTask, TaskBriefParent, TaskBriefSibling, TaskBriefProject, TaskBriefLogEntry, TaskBriefRequirement, } from "./v1.js";
+export { HenchConfigSchema, RunRecordSchema, validateConfig, validateRunRecord, formatValidationErrors, } from "./validate.js";
+export type { ValidationResult } from "./validate.js";
+export { BUILT_IN_TEMPLATES, findBuiltInTemplate } from "./templates.js";
+export type { WorkflowTemplate, TemplateConfigOverlay } from "./templates.js";

package/packages/hench/dist/schema/index.js

@@ -0,0 +1,4 @@
+export { HENCH_SCHEMA_VERSION, DEFAULT_HENCH_CONFIG, } from "./v1.js";
+export { HenchConfigSchema, RunRecordSchema, validateConfig, validateRunRecord, formatValidationErrors, } from "./validate.js";
+export { BUILT_IN_TEMPLATES, findBuiltInTemplate } from "./templates.js";
+//# sourceMappingURL=index.js.map

package/packages/hench/dist/schema/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/schema/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,SAAS,CAAC;AA4BjB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,eAAe,CAAC;AAIvB,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}