orkajs 1.3.2 → 1.4.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.0] - 2026-03-09
+
+### Added
+- **Human-in-the-Loop (HITL) Agent** - Full support for human oversight in agent workflows
+  - `HITLAgent` - Agent with built-in interrupt and checkpoint capabilities
+  - `MemoryCheckpointStore` - In-memory checkpoint storage for development
+  - Tool approval system with `requireApprovalFor` and `autoApproveTools` configuration
+  - Checkpoint system with configurable intervals (`checkpointEvery`)
+  - Resume from checkpoint support for long-running tasks
+  - Interrupt types: `tool_approval`, `checkpoint`, `review`, `confirmation`, `custom`
+  - Response types: `approved`, `rejected`, `modified`, `timeout`
+  - Custom `CheckpointStore` interface for Redis/PostgreSQL persistence
+  - `requestConfirmation()` and `requestReview()` methods for manual interrupts
+- New subpath export: `orkajs/agent/hitl`
+- Documentation: Human-in-the-Loop page added (EN/FR)
+
 ## [1.3.2] - 2026-03-07
 
 ### Added

package/README.md

@@ -13,6 +13,7 @@
   <a href="https://www.npmjs.com/package/orkajs"><img src="https://img.shields.io/npm/dm/orkajs.svg" alt="npm downloads"></a>
   <a href="https://github.com/orkajs/orkajs/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/orkajs.svg" alt="license"></a>
   <a href="https://orkajs.com"><img src="https://img.shields.io/badge/docs-orkajs.com-blue.svg" alt="documentation"></a>
+  <a href="https://discord.gg/zUbDmJVr"><img src="https://img.shields.io/badge/discord-join%20chat-7289da.svg" alt="discord"></a>
 </p>
 
 ---
@@ -23,21 +24,6 @@
 npm install orkajs
 ```
 
-### TypeScript Configuration
-
-OrkaJS works with all `moduleResolution` modes:
-
-```json
-{
-  "compilerOptions": {
-    "moduleResolution": "node"      // ✅ Legacy (supported)
-    // or "node16"                   // ✅ Modern
-    // or "nodenext"                 // ✅ Modern
-    // or "bundler"                  // ✅ Bundlers (Vite, Webpack)
-  }
-}
-```
-
 ## Quick Start
 
 ```typescript

package/agent/hitl.d.ts

@@ -0,0 +1 @@
+export * from '../dist/agent/hitl';

package/agent/hitl.js

@@ -0,0 +1 @@
+module.exports = require('../dist/agent/hitl.cjs');

package/dist/agent/hitl.cjs

@@ -0,0 +1,17 @@
+'use strict';
+
+var chunkBW7QJF67_cjs = require('../chunk-BW7QJF67.cjs');
+require('../chunk-HW4O3SWN.cjs');
+
+
+
+Object.defineProperty(exports, "HITLAgent", {
+  enumerable: true,
+  get: function () { return chunkBW7QJF67_cjs.HITLAgent; }
+});
+Object.defineProperty(exports, "MemoryCheckpointStore", {
+  enumerable: true,
+  get: function () { return chunkBW7QJF67_cjs.MemoryCheckpointStore; }
+});
+//# sourceMappingURL=hitl.cjs.map
+//# sourceMappingURL=hitl.cjs.map

package/dist/agent/hitl.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"hitl.cjs"}

package/dist/agent/hitl.d.cts

@@ -0,0 +1,118 @@
+import { LLMAdapter } from '../types/index.cjs';
+import { Memory } from '../memory/memory.cjs';
+import { B as BaseAgent } from '../base-agent-BlAOno3g.cjs';
+import { T as Tool, b as AgentPolicy, c as AgentResult } from '../types-ZpM642VC.cjs';
+import '../core/knowledge.cjs';
+
+type InterruptReason = 'tool_approval' | 'checkpoint' | 'review' | 'confirmation' | 'custom';
+type InterruptStatus = 'pending' | 'approved' | 'rejected' | 'modified' | 'timeout';
+interface InterruptRequest {
+    id: string;
+    agentId: string;
+    reason: InterruptReason;
+    message: string;
+    data: InterruptData;
+    createdAt: Date;
+    timeoutMs?: number;
+}
+interface InterruptData {
+    toolName?: string;
+    toolInput?: Record<string, unknown>;
+    stepNumber?: number;
+    thought?: string;
+    context?: Record<string, unknown>;
+}
+interface InterruptResponse {
+    id: string;
+    status: InterruptStatus;
+    modifiedData?: InterruptData;
+    feedback?: string;
+    respondedAt: Date;
+}
+interface Checkpoint {
+    id: string;
+    agentId: string;
+    stepNumber: number;
+    state: CheckpointState;
+    createdAt: Date;
+    metadata?: Record<string, unknown>;
+}
+interface CheckpointState {
+    input: string;
+    steps: CheckpointStep[];
+    context: Record<string, unknown>;
+}
+interface CheckpointStep {
+    thought: string;
+    action: string;
+    actionInput: Record<string, unknown>;
+    observation: string;
+}
+interface HITLConfig {
+    requireApprovalFor?: string[];
+    autoApproveTools?: string[];
+    checkpointEvery?: number;
+    defaultTimeoutMs?: number;
+    onInterrupt?: InterruptHandler;
+    checkpointStore?: CheckpointStore;
+}
+type InterruptHandler = (request: InterruptRequest) => Promise<InterruptResponse>;
+interface CheckpointStore {
+    save(checkpoint: Checkpoint): Promise<void>;
+    load(checkpointId: string): Promise<Checkpoint | null>;
+    loadLatest(agentId: string): Promise<Checkpoint | null>;
+    list(agentId: string): Promise<Checkpoint[]>;
+    delete(checkpointId: string): Promise<void>;
+}
+interface HITLAgentConfig {
+    name?: string;
+    goal: string;
+    tools: Tool[];
+    policy?: AgentPolicy;
+    systemPrompt?: string;
+    maxSteps?: number;
+    temperature?: number;
+    verbose?: boolean;
+    hitl: HITLConfig;
+}
+interface HITLAgentResult extends AgentResult {
+    interrupts: InterruptResponse[];
+    checkpoints: string[];
+    wasInterrupted: boolean;
+    resumedFromCheckpoint?: string;
+}
+
+declare class HITLAgent extends BaseAgent {
+    private verbose;
+    private hitlConfig;
+    private agentId;
+    private interrupts;
+    private checkpointIds;
+    constructor(config: HITLAgentConfig, llm: LLMAdapter, memory?: Memory);
+    run(input: string, resumeFromCheckpoint?: string): Promise<HITLAgentResult>;
+    interrupt(reason: InterruptReason, message: string, data?: InterruptData): Promise<InterruptResponse>;
+    requestConfirmation(message: string, context?: Record<string, unknown>): Promise<InterruptResponse>;
+    requestReview(message: string, stepNumber: number, thought: string): Promise<InterruptResponse>;
+    private handleToolApproval;
+    private createCheckpoint;
+    getCheckpoints(): Promise<Checkpoint[]>;
+    loadCheckpoint(checkpointId: string): Promise<Checkpoint | null>;
+    private buildHITLResult;
+    private buildSystemPrompt;
+    private buildPrompt;
+    private parseResponse;
+    private generateId;
+}
+
+declare class MemoryCheckpointStore implements CheckpointStore {
+    private checkpoints;
+    private agentCheckpoints;
+    save(checkpoint: Checkpoint): Promise<void>;
+    load(checkpointId: string): Promise<Checkpoint | null>;
+    loadLatest(agentId: string): Promise<Checkpoint | null>;
+    list(agentId: string): Promise<Checkpoint[]>;
+    delete(checkpointId: string): Promise<void>;
+    clear(): void;
+}
+
+export { type Checkpoint, type CheckpointState, type CheckpointStep, type CheckpointStore, HITLAgent, type HITLAgentConfig, type HITLAgentResult, type HITLConfig, type InterruptData, type InterruptHandler, type InterruptReason, type InterruptRequest, type InterruptResponse, type InterruptStatus, MemoryCheckpointStore };

package/dist/agent/hitl.d.ts

@@ -0,0 +1,118 @@
+import { LLMAdapter } from '../types/index.js';
+import { Memory } from '../memory/memory.js';
+import { B as BaseAgent } from '../base-agent-T9yoshsJ.js';
+import { T as Tool, b as AgentPolicy, c as AgentResult } from '../types-q1PSyGEh.js';
+import '../core/knowledge.js';
+
+type InterruptReason = 'tool_approval' | 'checkpoint' | 'review' | 'confirmation' | 'custom';
+type InterruptStatus = 'pending' | 'approved' | 'rejected' | 'modified' | 'timeout';
+interface InterruptRequest {
+    id: string;
+    agentId: string;
+    reason: InterruptReason;
+    message: string;
+    data: InterruptData;
+    createdAt: Date;
+    timeoutMs?: number;
+}
+interface InterruptData {
+    toolName?: string;
+    toolInput?: Record<string, unknown>;
+    stepNumber?: number;
+    thought?: string;
+    context?: Record<string, unknown>;
+}
+interface InterruptResponse {
+    id: string;
+    status: InterruptStatus;
+    modifiedData?: InterruptData;
+    feedback?: string;
+    respondedAt: Date;
+}
+interface Checkpoint {
+    id: string;
+    agentId: string;
+    stepNumber: number;
+    state: CheckpointState;
+    createdAt: Date;
+    metadata?: Record<string, unknown>;
+}
+interface CheckpointState {
+    input: string;
+    steps: CheckpointStep[];
+    context: Record<string, unknown>;
+}
+interface CheckpointStep {
+    thought: string;
+    action: string;
+    actionInput: Record<string, unknown>;
+    observation: string;
+}
+interface HITLConfig {
+    requireApprovalFor?: string[];
+    autoApproveTools?: string[];
+    checkpointEvery?: number;
+    defaultTimeoutMs?: number;
+    onInterrupt?: InterruptHandler;
+    checkpointStore?: CheckpointStore;
+}
+type InterruptHandler = (request: InterruptRequest) => Promise<InterruptResponse>;
+interface CheckpointStore {
+    save(checkpoint: Checkpoint): Promise<void>;
+    load(checkpointId: string): Promise<Checkpoint | null>;
+    loadLatest(agentId: string): Promise<Checkpoint | null>;
+    list(agentId: string): Promise<Checkpoint[]>;
+    delete(checkpointId: string): Promise<void>;
+}
+interface HITLAgentConfig {
+    name?: string;
+    goal: string;
+    tools: Tool[];
+    policy?: AgentPolicy;
+    systemPrompt?: string;
+    maxSteps?: number;
+    temperature?: number;
+    verbose?: boolean;
+    hitl: HITLConfig;
+}
+interface HITLAgentResult extends AgentResult {
+    interrupts: InterruptResponse[];
+    checkpoints: string[];
+    wasInterrupted: boolean;
+    resumedFromCheckpoint?: string;
+}
+
+declare class HITLAgent extends BaseAgent {
+    private verbose;
+    private hitlConfig;
+    private agentId;
+    private interrupts;
+    private checkpointIds;
+    constructor(config: HITLAgentConfig, llm: LLMAdapter, memory?: Memory);
+    run(input: string, resumeFromCheckpoint?: string): Promise<HITLAgentResult>;
+    interrupt(reason: InterruptReason, message: string, data?: InterruptData): Promise<InterruptResponse>;
+    requestConfirmation(message: string, context?: Record<string, unknown>): Promise<InterruptResponse>;
+    requestReview(message: string, stepNumber: number, thought: string): Promise<InterruptResponse>;
+    private handleToolApproval;
+    private createCheckpoint;
+    getCheckpoints(): Promise<Checkpoint[]>;
+    loadCheckpoint(checkpointId: string): Promise<Checkpoint | null>;
+    private buildHITLResult;
+    private buildSystemPrompt;
+    private buildPrompt;
+    private parseResponse;
+    private generateId;
+}
+
+declare class MemoryCheckpointStore implements CheckpointStore {
+    private checkpoints;
+    private agentCheckpoints;
+    save(checkpoint: Checkpoint): Promise<void>;
+    load(checkpointId: string): Promise<Checkpoint | null>;
+    loadLatest(agentId: string): Promise<Checkpoint | null>;
+    list(agentId: string): Promise<Checkpoint[]>;
+    delete(checkpointId: string): Promise<void>;
+    clear(): void;
+}
+
+export { type Checkpoint, type CheckpointState, type CheckpointStep, type CheckpointStore, HITLAgent, type HITLAgentConfig, type HITLAgentResult, type HITLConfig, type InterruptData, type InterruptHandler, type InterruptReason, type InterruptRequest, type InterruptResponse, type InterruptStatus, MemoryCheckpointStore };

package/dist/agent/hitl.js

@@ -0,0 +1,4 @@
+export { HITLAgent, MemoryCheckpointStore } from '../chunk-YHRCEYN3.js';
+import '../chunk-QQAP3IF5.js';
+//# sourceMappingURL=hitl.js.map
+//# sourceMappingURL=hitl.js.map

package/dist/agent/hitl.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"hitl.js"}

package/dist/agent/index.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var chunkBW7QJF67_cjs = require('../chunk-BW7QJF67.cjs');
 var chunkYTFRKPLP_cjs = require('../chunk-YTFRKPLP.cjs');
 var chunkY5EM3P55_cjs = require('../chunk-Y5EM3P55.cjs');
 var chunk5PY2DAI6_cjs = require('../chunk-5PY2DAI6.cjs');
@@ -11,6 +12,14 @@ var chunkHW4O3SWN_cjs = require('../chunk-HW4O3SWN.cjs');
 
 
 
+Object.defineProperty(exports, "HITLAgent", {
+  enumerable: true,
+  get: function () { return chunkBW7QJF67_cjs.HITLAgent; }
+});
+Object.defineProperty(exports, "MemoryCheckpointStore", {
+  enumerable: true,
+  get: function () { return chunkBW7QJF67_cjs.MemoryCheckpointStore; }
+});
 Object.defineProperty(exports, "Agent", {
   enumerable: true,
   get: function () { return chunkYTFRKPLP_cjs.Agent; }

package/dist/agent/index.d.cts

@@ -6,6 +6,7 @@ export { OpenAIFunctionsAgent } from './openai-functions.cjs';
 export { StructuredChatAgent } from './structured-chat.cjs';
 export { SQLToolkit } from './toolkits/sql.cjs';
 export { CSVToolkit } from './toolkits/csv.cjs';
+export { Checkpoint, CheckpointState, CheckpointStep, CheckpointStore, HITLAgent, HITLAgentConfig, HITLAgentResult, HITLConfig, InterruptData, InterruptHandler, InterruptReason, InterruptRequest, InterruptResponse, InterruptStatus, MemoryCheckpointStore } from './hitl.cjs';
 export { A as AgentConfig, a as AgentContext, b as AgentPolicy, c as AgentResult, d as AgentStepResult, e as AgentToolkit, C as CSVToolkitConfig, O as OpenAIFunction, f as OpenAIFunctionsAgentConfig, P as PlanAndExecuteAgentConfig, g as PlanAndExecuteResult, h as PlanStep, R as ReActAgentConfig, S as SQLToolkitConfig, i as StructuredChatAgentConfig, T as Tool, j as ToolParameter, k as ToolResult } from '../types-ZpM642VC.cjs';
 import '../types/index.cjs';
 import '../core/knowledge.cjs';

package/dist/agent/index.d.ts

@@ -6,6 +6,7 @@ export { OpenAIFunctionsAgent } from './openai-functions.js';
 export { StructuredChatAgent } from './structured-chat.js';
 export { SQLToolkit } from './toolkits/sql.js';
 export { CSVToolkit } from './toolkits/csv.js';
+export { Checkpoint, CheckpointState, CheckpointStep, CheckpointStore, HITLAgent, HITLAgentConfig, HITLAgentResult, HITLConfig, InterruptData, InterruptHandler, InterruptReason, InterruptRequest, InterruptResponse, InterruptStatus, MemoryCheckpointStore } from './hitl.js';
 export { A as AgentConfig, a as AgentContext, b as AgentPolicy, c as AgentResult, d as AgentStepResult, e as AgentToolkit, C as CSVToolkitConfig, O as OpenAIFunction, f as OpenAIFunctionsAgentConfig, P as PlanAndExecuteAgentConfig, g as PlanAndExecuteResult, h as PlanStep, R as ReActAgentConfig, S as SQLToolkitConfig, i as StructuredChatAgentConfig, T as Tool, j as ToolParameter, k as ToolResult } from '../types-q1PSyGEh.js';
 import '../types/index.js';
 import '../core/knowledge.js';

package/dist/agent/index.js

@@ -1,3 +1,4 @@
+export { HITLAgent, MemoryCheckpointStore } from '../chunk-YHRCEYN3.js';
 export { Agent } from '../chunk-37ZKQRCK.js';
 export { SQLToolkit } from '../chunk-EHRXFND7.js';
 export { CSVToolkit } from '../chunk-XENO7X2J.js';