@n-dx/core 0.1.0

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

@@ -0,0 +1,34 @@
+/**
+ * Workflow template definitions.
+ *
+ * Templates are pre-configured workflow setups for common development patterns.
+ * Each template provides a partial HenchConfig overlay that gets merged with
+ * the current config when applied.
+ */
+import type { HenchConfig } from "./v1.js";
+/**
+ * Partial config overlay — only the fields a template wants to change.
+ * The `schema` field is excluded since it's not user-configurable.
+ */
+export type TemplateConfigOverlay = Partial<Omit<HenchConfig, "schema">>;
+export interface WorkflowTemplate {
+    /** Unique template ID (slug format: lowercase, hyphens). */
+    id: string;
+    /** Human-readable display name. */
+    name: string;
+    /** One-line description of what this template optimizes for. */
+    description: string;
+    /** Recommended use cases (shown in UI and CLI). */
+    useCases: string[];
+    /** Tags for filtering/searching. */
+    tags: string[];
+    /** Config fields this template overrides. */
+    config: TemplateConfigOverlay;
+    /** Whether this is a built-in template (not deletable). */
+    builtIn: boolean;
+    /** ISO timestamp of when this template was created (user templates only). */
+    createdAt?: string;
+}
+export declare const BUILT_IN_TEMPLATES: WorkflowTemplate[];
+/** Look up a built-in template by ID. */
+export declare function findBuiltInTemplate(id: string): WorkflowTemplate | undefined;

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

@@ -0,0 +1,147 @@
+/**
+ * Workflow template definitions.
+ *
+ * Templates are pre-configured workflow setups for common development patterns.
+ * Each template provides a partial HenchConfig overlay that gets merged with
+ * the current config when applied.
+ */
+// ── Built-in templates ────────────────────────────────────────────────
+export const BUILT_IN_TEMPLATES = [
+    {
+        id: "quick-iteration",
+        name: "Quick Iteration",
+        description: "Short, fast runs for rapid prototyping and small fixes",
+        useCases: [
+            "Bug fixes and small patches",
+            "Quick refactors with clear scope",
+            "Exploratory changes with fast feedback",
+        ],
+        tags: ["fast", "lightweight", "prototyping"],
+        config: {
+            maxTurns: 15,
+            tokenBudget: 50000,
+            loopPauseMs: 500,
+            retry: {
+                maxRetries: 2,
+                baseDelayMs: 1000,
+                maxDelayMs: 10000,
+            },
+        },
+        builtIn: true,
+    },
+    {
+        id: "thorough-execution",
+        name: "Thorough Execution",
+        description: "Extended runs with generous limits for complex multi-file tasks",
+        useCases: [
+            "New feature implementation across multiple files",
+            "Large refactoring efforts",
+            "Tasks requiring extensive test writing",
+        ],
+        tags: ["thorough", "complex", "multi-file"],
+        config: {
+            maxTurns: 80,
+            maxTokens: 16384,
+            tokenBudget: 200000,
+            loopPauseMs: 2000,
+            retry: {
+                maxRetries: 5,
+                baseDelayMs: 2000,
+                maxDelayMs: 60000,
+            },
+        },
+        builtIn: true,
+    },
+    {
+        id: "budget-conscious",
+        name: "Budget Conscious",
+        description: "Optimized for minimal token usage while maintaining quality",
+        useCases: [
+            "Cost-sensitive environments",
+            "High-volume task processing",
+            "Routine maintenance tasks",
+        ],
+        tags: ["budget", "cost-effective", "efficient"],
+        config: {
+            maxTurns: 20,
+            maxTokens: 4096,
+            tokenBudget: 30000,
+            loopPauseMs: 3000,
+            retry: {
+                maxRetries: 2,
+                baseDelayMs: 3000,
+                maxDelayMs: 15000,
+            },
+        },
+        builtIn: true,
+    },
+    {
+        id: "strict-safety",
+        name: "Strict Safety",
+        description: "Maximum guard rails for sensitive codebases and production-adjacent work",
+        useCases: [
+            "Production infrastructure changes",
+            "Security-sensitive code modifications",
+            "Regulated environments requiring audit trails",
+        ],
+        tags: ["safety", "security", "production"],
+        config: {
+            maxTurns: 30,
+            maxFailedAttempts: 2,
+            guard: {
+                blockedPaths: [
+                    ".hench/**",
+                    ".rex/**",
+                    ".git/**",
+                    "node_modules/**",
+                    ".env*",
+                    "*.pem",
+                    "*.key",
+                    "**/secrets/**",
+                    "**/credentials/**",
+                ],
+                allowedCommands: ["npm", "npx", "node", "git", "tsc", "vitest"],
+                commandTimeout: 15000,
+                maxFileSize: 524288,
+                spawnTimeout: 120000, // 2 minutes — stricter than default
+                maxConcurrentProcesses: 2, // tighter limit for sensitive work
+                allowedGitSubcommands: [
+                    "status", "add", "commit", "diff", "log",
+                    "branch", "show", "rev-parse",
+                ], // no checkout/stash in strict mode
+                policy: {
+                    maxCommandsPerMinute: 30, // half of default
+                    maxWritesPerMinute: 15, // half of default
+                },
+            },
+        },
+        builtIn: true,
+    },
+    {
+        id: "api-direct",
+        name: "API Direct",
+        description: "Use Anthropic API directly instead of Claude Code CLI for headless environments",
+        useCases: [
+            "CI/CD pipeline integration",
+            "Headless server environments",
+            "Custom API key management",
+        ],
+        tags: ["api", "headless", "ci-cd"],
+        config: {
+            provider: "api",
+            maxTurns: 40,
+            tokenBudget: 150000,
+            retry: {
+                maxRetries: 4,
+                baseDelayMs: 3000,
+                maxDelayMs: 30000,
+            },
+        },
+        builtIn: true,
+    },
+];
+/** Look up a built-in template by ID. */
+export function findBuiltInTemplate(id) {
+    return BUILT_IN_TEMPLATES.find((t) => t.id === id);
+}
+//# sourceMappingURL=templates.js.map

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

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

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

@@ -0,0 +1,235 @@
+export type { MemoryThrottleConfig } from "../process/memory-throttle.js";
+export type { MemoryMonitorConfig } from "../process/memory-monitor.js";
+export type { RuntimePoolConfig } from "../process/pool.js";
+import type { MemoryThrottleConfig } from "../process/memory-throttle.js";
+import type { MemoryMonitorConfig } from "../process/memory-monitor.js";
+import type { RuntimePoolConfig } from "../process/pool.js";
+export declare const HENCH_SCHEMA_VERSION = "hench/v1";
+/**
+ * Configurable subset of policy limits (all optional, defaults applied at runtime).
+ *
+ * Defined here (schema) rather than in guard/contracts so that schema/v1
+ * stays self-contained and guard stays free of schema imports.  The two
+ * definitions are structurally identical; TypeScript's structural typing
+ * ensures they remain compatible wherever HenchConfig.guard is passed to
+ * GuardRails (which accepts the guard-owned GuardConfig interface).
+ */
+export interface PolicyLimitsConfig {
+    /** Maximum commands per minute (0 = unlimited). */
+    maxCommandsPerMinute?: number;
+    /** Maximum file writes per minute (0 = unlimited). */
+    maxWritesPerMinute?: number;
+    /** Maximum total bytes written in the session (0 = unlimited). */
+    maxTotalBytesWritten?: number;
+    /** Maximum total commands in the session (0 = unlimited). */
+    maxTotalCommands?: number;
+}
+/**
+ * Security guard configuration embedded in {@link HenchConfig}.
+ *
+ * Defined here (schema) rather than in guard/contracts so that schema/v1
+ * stays self-contained and guard stays free of schema imports.  The two
+ * definitions are structurally identical; TypeScript's structural typing
+ * ensures they remain compatible wherever HenchConfig.guard is passed to
+ * GuardRails (which accepts the guard-owned GuardConfig interface).
+ */
+export interface GuardConfig {
+    blockedPaths: string[];
+    allowedCommands: string[];
+    commandTimeout: number;
+    maxFileSize: number;
+    /** Timeout in ms for spawn-based execution (spawnTool/spawnManaged). 0 = no timeout. */
+    spawnTimeout: number;
+    /** Maximum concurrent child processes allowed. */
+    maxConcurrentProcesses: number;
+    /** Allowed git subcommands. Centralizes the git safety allowlist in guard config. */
+    allowedGitSubcommands: string[];
+    /** Policy limits for session-aware rate limiting and resource tracking. */
+    policy?: PolicyLimitsConfig;
+    /** Memory-based execution throttling configuration. */
+    memoryThrottle?: Partial<MemoryThrottleConfig>;
+    /** Pre-spawn memory monitoring configuration. */
+    memoryMonitor?: Partial<MemoryMonitorConfig>;
+    /** Runtime process pool configuration for warm worker reuse. */
+    pool?: Partial<RuntimePoolConfig>;
+}
+export interface RetryConfig {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+}
+export type Provider = "cli" | "api";
+export interface HenchConfig {
+    schema: string;
+    provider: Provider;
+    model: string;
+    maxTurns: number;
+    maxTokens: number;
+    /** Total token budget per run (input + output). 0 = unlimited. */
+    tokenBudget: number;
+    rexDir: string;
+    apiKeyEnv: string;
+    guard: GuardConfig;
+    retry: RetryConfig;
+    loopPauseMs: number;
+    maxFailedAttempts: number;
+    /** When true, the agent is running in self-heal mode (structural fixes). */
+    selfHeal?: boolean;
+}
+export declare function DEFAULT_HENCH_CONFIG(): HenchConfig;
+export type RunStatus = "running" | "completed" | "failed" | "timeout" | "budget_exceeded" | "error_transient";
+export interface ToolCallRecord {
+    turn: number;
+    tool: string;
+    input: Record<string, unknown>;
+    output: string;
+    durationMs: number;
+}
+export interface TokenUsage {
+    input: number;
+    output: number;
+    cacheCreationInput?: number;
+    cacheReadInput?: number;
+}
+/** Token usage for a single API turn. */
+export interface TurnTokenUsage {
+    turn: number;
+    input: number;
+    output: number;
+    cacheCreationInput?: number;
+    cacheReadInput?: number;
+    /** LLM vendor used for this token event (e.g. "claude", "codex"). */
+    vendor?: string;
+    /** Model used for this token event. */
+    model?: string;
+}
+export interface CommandRecord {
+    command: string;
+    exitStatus: "ok" | "error" | "timeout" | "blocked";
+    durationMs: number;
+}
+export interface TestRecord {
+    command: string;
+    passed: boolean;
+    durationMs: number;
+}
+export interface SummaryCounts {
+    filesRead: number;
+    filesChanged: number;
+    commandsExecuted: number;
+    testsRun: number;
+    toolCallsTotal: number;
+}
+export interface PostRunTestRecord {
+    /** Whether tests were executed. */
+    ran: boolean;
+    /** Whether all tests passed. */
+    passed: boolean;
+    /** The command that was executed. */
+    command?: string;
+    /** Human-readable test output (truncated). */
+    output?: string;
+    /** Duration in ms. */
+    durationMs?: number;
+    /** Test files that were specifically targeted. Empty if full suite. */
+    targetedFiles: string[];
+    /** Error message if tests couldn't be run. */
+    error?: string;
+}
+export interface RunSummaryData {
+    filesChanged: string[];
+    filesRead: string[];
+    commandsExecuted: CommandRecord[];
+    testsRun: TestRecord[];
+    /** Automatic post-task test results. */
+    postRunTests?: PostRunTestRecord;
+    counts: SummaryCounts;
+}
+export interface RunMemoryStats {
+    /** Peak RSS of the hench process during this run (bytes). */
+    peakRssBytes: number;
+    /** System available memory at run start (bytes). -1 if unavailable. */
+    systemAvailableAtStartBytes: number;
+    /** System available memory at run end (bytes). -1 if unavailable. */
+    systemAvailableAtEndBytes: number;
+    /** System total memory (bytes). */
+    systemTotalBytes: number;
+}
+export interface RunRecord {
+    id: string;
+    taskId: string;
+    taskTitle: string;
+    startedAt: string;
+    finishedAt?: string;
+    /** ISO timestamp of the most recent agent activity. Updated on every periodic save. */
+    lastActivityAt?: string;
+    status: RunStatus;
+    turns: number;
+    summary?: string;
+    error?: string;
+    tokenUsage: TokenUsage;
+    /** Per-turn token breakdown. One entry per API call. */
+    turnTokenUsage?: TurnTokenUsage[];
+    toolCalls: ToolCallRecord[];
+    model: string;
+    retryAttempts?: number;
+    /** Structured metadata derived from tool calls at run finalization. */
+    structuredSummary?: RunSummaryData;
+    /** Memory usage statistics captured during the run. */
+    memoryStats?: RunMemoryStats;
+}
+export interface TaskBriefTask {
+    id: string;
+    title: string;
+    level: string;
+    status: string;
+    description?: string;
+    acceptanceCriteria?: string[];
+    priority?: string;
+    tags?: string[];
+    blockedBy?: string[];
+    failureReason?: string;
+}
+export interface TaskBriefParent {
+    id: string;
+    title: string;
+    level: string;
+    description?: string;
+}
+export interface TaskBriefSibling {
+    id: string;
+    title: string;
+    status: string;
+}
+export interface TaskBriefProject {
+    name: string;
+    validateCommand?: string;
+    testCommand?: string;
+}
+export interface TaskBriefLogEntry {
+    timestamp: string;
+    event: string;
+    detail?: string;
+}
+/**
+ * A requirement included in the task brief for agent awareness.
+ */
+export interface TaskBriefRequirement {
+    id: string;
+    title: string;
+    category: string;
+    validationType: string;
+    acceptanceCriteria: string[];
+    /** Where this requirement was defined (item title). */
+    source: string;
+}
+export interface TaskBrief {
+    task: TaskBriefTask;
+    parentChain: TaskBriefParent[];
+    siblings: TaskBriefSibling[];
+    /** Requirements that apply to this task (own + inherited). */
+    requirements: TaskBriefRequirement[];
+    project: TaskBriefProject;
+    workflow: string;
+    recentLog: TaskBriefLogEntry[];
+}

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

@@ -0,0 +1,34 @@
+import { PROJECT_DIRS } from "../prd/llm-gateway.js";
+export const HENCH_SCHEMA_VERSION = "hench/v1";
+export function DEFAULT_HENCH_CONFIG() {
+    return {
+        schema: HENCH_SCHEMA_VERSION,
+        provider: "cli",
+        model: "sonnet",
+        maxTurns: 50,
+        maxTokens: 8192,
+        tokenBudget: 0,
+        rexDir: PROJECT_DIRS.REX,
+        apiKeyEnv: "ANTHROPIC_API_KEY",
+        guard: {
+            blockedPaths: [`${PROJECT_DIRS.HENCH}/**`, `${PROJECT_DIRS.REX}/**`, ".git/**", "node_modules/**"],
+            allowedCommands: ["npm", "npx", "node", "git", "tsc", "vitest"],
+            commandTimeout: 30000,
+            maxFileSize: 1048576,
+            spawnTimeout: 300000, // 5 minutes
+            maxConcurrentProcesses: 3,
+            allowedGitSubcommands: [
+                "status", "add", "commit", "diff", "log",
+                "branch", "checkout", "stash", "show", "rev-parse",
+            ],
+        },
+        retry: {
+            maxRetries: 3,
+            baseDelayMs: 2000,
+            maxDelayMs: 30000,
+        },
+        loopPauseMs: 2000,
+        maxFailedAttempts: 3,
+    };
+}
+//# sourceMappingURL=v1.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"v1.js","sourceRoot":"","sources":["../../src/schema/v1.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAQrD,MAAM,CAAC,MAAM,oBAAoB,GAAG,UAAU,CAAC;AA8E/C,MAAM,UAAU,oBAAoB;IAClC,OAAO;QACL,MAAM,EAAE,oBAAoB;QAC5B,QAAQ,EAAE,KAAK;QACf,KAAK,EAAE,QAAQ;QACf,QAAQ,EAAE,EAAE;QACZ,SAAS,EAAE,IAAI;QACf,WAAW,EAAE,CAAC;QACd,MAAM,EAAE,YAAY,CAAC,GAAG;QACxB,SAAS,EAAE,mBAAmB;QAC9B,KAAK,EAAE;YACL,YAAY,EAAE,CAAC,GAAG,YAAY,CAAC,KAAK,KAAK,EAAE,GAAG,YAAY,CAAC,GAAG,KAAK,EAAE,SAAS,EAAE,iBAAiB,CAAC;YAClG,eAAe,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;YAC/D,cAAc,EAAE,KAAK;YACrB,WAAW,EAAE,OAAO;YACpB,YAAY,EAAE,MAAM,EAAW,YAAY;YAC3C,sBAAsB,EAAE,CAAC;YACzB,qBAAqB,EAAE;gBACrB,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK;gBACxC,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW;aACnD;SACF;QACD,KAAK,EAAE;YACL,UAAU,EAAE,CAAC;YACb,WAAW,EAAE,IAAI;YACjB,UAAU,EAAE,KAAK;SAClB;QACD,WAAW,EAAE,IAAI;QACjB,iBAAiB,EAAE,CAAC;KACrB,CAAC;AACJ,CAAC"}