@almadar/agent 1.6.4 → 2.0.1

package/LICENSE

@@ -1,72 +1,21 @@
-Business Source License 1.1
-
-Parameters
-
-Licensor:             Almadar FZE
-Licensed Work:        KFlow Builder / Almadar
-                      The Licensed Work is (c) 2025-2026 Almadar FZE.
-Additional Use Grant: You may make production use of the Licensed Work for
-                      non-commercial purposes and for internal evaluation.
-                      Production use for commercial purposes requires a
-                      commercial license from the Licensor.
-Change Date:          2030-02-01
-Change License:       Apache License, Version 2.0
-
-Terms
-
-The Licensor hereby grants you the right to copy, modify, create derivative
-works, redistribute, and make non-production use of the Licensed Work. The
-Licensor may make an Additional Use Grant, above, permitting limited
-production use.
-
-Effective on the Change Date, or the fourth anniversary of the first publicly
-available distribution of a specific version of the Licensed Work under this
-License, whichever comes first, the Licensor hereby grants you rights under
-the terms of the Change License, and the rights granted in the paragraph
-above terminate.
-
-If your use of the Licensed Work does not comply with the requirements
-currently in effect as described in this License, you must purchase a
-commercial license from the Licensor, its affiliated entities, or authorized
-resellers, or you must refrain from using the Licensed Work.
-
-All copies of the original and modified Licensed Work, and derivative works
-of the Licensed Work, are subject to this License. This License applies
-separately for each version of the Licensed Work and the Change Date may vary
-for each version of the Licensed Work released by Licensor.
-
-You must conspicuously display this License on each original or modified copy
-of the Licensed Work. If you receive the Licensed Work in original or
-modified form from a third party, the terms and conditions set forth in this
-License apply to your use of that work.
-
-Any use of the Licensed Work in violation of this License will automatically
-terminate your rights under this License for the current and all other
-versions of the Licensed Work.
-
-This License does not grant you any right in any trademark or logo of
-Licensor or its affiliates (provided that you may use a trademark or logo of
-Licensor as expressly required by this License).
-
-TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
-AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
-EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
-TITLE.
-
----
-
-License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
-"Business Source License" is a trademark of MariaDB Corporation Ab.
-
-ADDITIONAL TERMS:
-
-Documentation (builder/packages/website/docs/) is licensed under CC BY 4.0.
-
-TRADEMARKS:
-
-"Orbital", "KFlow", "Almadar", and the Almadar logo are trademarks of
-Almadar FZE. You may not use these trademarks without prior written
-permission from Almadar FZE.
-
-For licensing inquiries: licensing@almadar.io
+MIT License
+
+Copyright (c) 2026 Almadar Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# @almadar/agent
+
+> AI agent infrastructure for Almadar orbital schema generation
+
+Part of the [Almadar](https://github.com/almadar-io/almadar) platform.
+
+## Installation
+
+```bash
+npm install @almadar/agent
+```
+
+## Usage
+
+```typescript
+import { /* ... */ } from '@almadar/agent';
+```
+
+## API
+
+<!-- Document public exports here -->
+
+## License
+
+MIT

package/dist/agent/event-budget.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Event Budget Configuration
+ *
+ * Prevents runaway agent loops with soft/hard event limits per skill.
+ */
+/**
+ * Event budget limits for different skills.
+ * - soft: Warning threshold (agent reminded to finish up)
+ * - hard: Maximum events before forced completion
+ */
+export declare const EVENT_BUDGETS: Record<string, {
+    soft: number;
+    hard: number;
+}>;
+/**
+ * Get event budget for a skill.
+ */
+export declare function getEventBudget(skillName: string): {
+    soft: number;
+    hard: number;
+};
+/**
+ * Generate a budget warning message to inject into the agent.
+ */
+export declare function getBudgetWarningMessage(eventCount: number, budget: {
+    soft: number;
+    hard: number;
+}): string | null;

package/dist/agent/experimental/hitl-v2.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Human-in-the-Loop v2 - Phase 2.3
+ *
+ * Structured interrupts with memory and time-travel debugging.
+ * Interrupt types: confirm, edit, select, text
+ *
+ * @packageDocumentation
+ */
+import type { MemoryManager } from '../../memory/MemoryManager.js';
+export type InterruptType = 'confirm' | 'edit' | 'select' | 'text';
+export interface InterruptRequest<T = unknown> {
+    interruptId: string;
+    sessionId: string;
+    type: InterruptType;
+    title: string;
+    description: string;
+    context: InterruptContext;
+    payload: T;
+    timeoutMs?: number;
+    createdAt: Date;
+}
+export interface InterruptContext {
+    checkpointId: string;
+    currentState: string;
+    previousActions: string[];
+    relevantMemory?: string[];
+}
+export interface InterruptResponse<T = unknown> {
+    interruptId: string;
+    response: T;
+    respondedAt: Date;
+    userId?: string;
+}
+export interface ConfirmPayload {
+    question: string;
+    defaultValue?: boolean;
+    severity: 'info' | 'warning' | 'critical';
+}
+export interface EditPayload {
+    content: string;
+    format: 'json' | 'text' | 'code';
+    schema?: Record<string, unknown>;
+    validationRules?: string[];
+}
+export interface SelectPayload {
+    options: Array<{
+        id: string;
+        label: string;
+        description?: string;
+        disabled?: boolean;
+    }>;
+    multiple?: boolean;
+    maxSelections?: number;
+}
+export interface TextPayload {
+    placeholder?: string;
+    multiline?: boolean;
+    maxLength?: number;
+    validation?: 'email' | 'url' | 'regex';
+    validationRegex?: string;
+}
+export interface HITLv2Options {
+    memoryManager?: MemoryManager;
+    defaultTimeoutMs?: number;
+    onInterrupt?: (request: InterruptRequest) => void;
+    onResponse?: (request: InterruptRequest, response: InterruptResponse) => void;
+}
+export declare class HITLv2Manager {
+    private options;
+    private pendingInterrupts;
+    private responses;
+    private checkpoints;
+    constructor(options?: HITLv2Options);
+    /**
+     * Create a confirmation interrupt
+     */
+    confirm(sessionId: string, question: string, options?: {
+        severity?: 'info' | 'warning' | 'critical';
+        defaultValue?: boolean;
+        timeoutMs?: number;
+        context?: Partial<InterruptContext>;
+    }): Promise<boolean>;
+    /**
+     * Create an edit interrupt
+     */
+    edit(sessionId: string, content: string, options?: {
+        format?: 'json' | 'text' | 'code';
+        title?: string;
+        description?: string;
+        schema?: Record<string, unknown>;
+        timeoutMs?: number;
+        context?: Partial<InterruptContext>;
+    }): Promise<string>;
+    /**
+     * Create a selection interrupt
+     */
+    select<T extends string>(sessionId: string, options: Array<{
+        id: T;
+        label: string;
+        description?: string;
+    }>, config?: {
+        title?: string;
+        description?: string;
+        multiple?: boolean;
+        timeoutMs?: number;
+        context?: Partial<InterruptContext>;
+    }): Promise<T | T[]>;
+    /**
+     * Create a text input interrupt
+     */
+    text(sessionId: string, options?: {
+        title?: string;
+        description?: string;
+        placeholder?: string;
+        multiline?: boolean;
+        maxLength?: number;
+        timeoutMs?: number;
+        context?: Partial<InterruptContext>;
+    }): Promise<string>;
+    /**
+     * Submit a response to an interrupt
+     */
+    submitResponse<T>(interruptId: string, response: T, userId?: string): Promise<void>;
+    /**
+     * Cancel an interrupt
+     */
+    cancelInterrupt(interruptId: string, reason?: string): void;
+    /**
+     * Save a checkpoint for time-travel
+     */
+    saveCheckpoint(checkpointId: string, state: unknown): void;
+    /**
+     * Restore a checkpoint
+     */
+    restoreCheckpoint<T>(checkpointId: string): T | null;
+    /**
+     * List available checkpoints
+     */
+    listCheckpoints(): string[];
+    /**
+     * Rewind to checkpoint and continue
+     */
+    rewindToCheckpoint<T>(checkpointId: string, sessionId: string, modifyFn?: (state: T) => T): Promise<T | null>;
+    /**
+     * Get interrupt statistics
+     */
+    getStats(): {
+        pendingCount: number;
+        totalHandled: number;
+        checkpointsCount: number;
+        averageResponseTimeMs: number;
+    };
+    /**
+     * Get pending interrupts for a session
+     */
+    getPendingForSession(sessionId: string): InterruptRequest[];
+    private createInterrupt;
+    private waitForResponse;
+    private storeInteraction;
+}
+export declare function createHITLv2Manager(options?: HITLv2Options): HITLv2Manager;

package/dist/agent/experimental/hitl-workflow-integration.d.ts

@@ -0,0 +1,182 @@
+/**
+ * HITL Workflow Integration - Phase 3.4
+ *
+ * Human-in-the-Loop with workflow-based conditional branching.
+ * Enables complex approval flows with human gates.
+ *
+ * @packageDocumentation
+ */
+import { HITLv2Manager } from './hitl-v2.js';
+import type { MemoryManager } from '../../memory/MemoryManager.js';
+/**
+ * Human gate types
+ */
+export type HumanGateType = 'approval' | 'edit' | 'select' | 'custom';
+/**
+ * Human gate configuration
+ */
+export interface HumanGate {
+    /** Gate ID */
+    id: string;
+    /** Gate type */
+    type: HumanGateType;
+    /** Display title */
+    title: string;
+    /** Description */
+    description: string;
+    /** Gate condition - when to show */
+    condition?: (context: unknown) => boolean;
+    /** Timeout in ms */
+    timeoutMs?: number;
+    /** Auto-approve if condition met */
+    autoApprove?: {
+        condition: (context: unknown) => boolean;
+        reason: string;
+    };
+    /** Gate-specific payload */
+    payload?: Record<string, unknown>;
+}
+/**
+ * Human gate result
+ */
+export interface HumanGateResult {
+    gateId: string;
+    approved: boolean;
+    response: unknown;
+    respondedAt: number;
+    userId?: string;
+    autoApproved: boolean;
+}
+/**
+ * Workflow branch definition
+ */
+export interface WorkflowBranch {
+    /** Branch ID */
+    id: string;
+    /** Branch condition */
+    condition: (context: unknown) => boolean;
+    /** Steps to execute */
+    steps: Array<{
+        tool: string;
+        input: Record<string, unknown>;
+    }>;
+    /** Human gate before branch */
+    gate?: HumanGate;
+}
+/**
+ * HITL workflow definition
+ */
+export interface HITLWorkflowDefinition {
+    /** Workflow name */
+    name: string;
+    /** Initial steps (before any gates) */
+    initialSteps: Array<{
+        tool: string;
+        input: Record<string, unknown>;
+    }>;
+    /** Human gates with conditional branches */
+    gates: HumanGate[];
+    /** Branches based on gate outcomes */
+    branches: WorkflowBranch[];
+    /** Fallback if no branches match */
+    fallbackBranch?: WorkflowBranch;
+}
+/**
+ * HITL workflow result
+ */
+export interface HITLWorkflowResult {
+    success: boolean;
+    output: unknown;
+    gatesPassed: HumanGateResult[];
+    branchesTaken: string[];
+    durationMs: number;
+    wasInterrupted: boolean;
+}
+/**
+ * HITL workflow options
+ */
+export interface HITLWorkflowOptions {
+    /** HITL manager */
+    hitlManager: HITLv2Manager;
+    /** Tool executor */
+    toolExecutor: {
+        execute(tool: string, input: Record<string, unknown>): Promise<unknown>;
+    };
+    /** Memory manager */
+    memoryManager?: MemoryManager;
+    /** Default gate timeout */
+    defaultTimeoutMs?: number;
+    /** Enable auto-approval learning */
+    enableAutoApprove?: boolean;
+}
+export declare class HITLWorkflowEngine {
+    private workflowEngine;
+    private hitlManager;
+    private options;
+    private gateHistory;
+    constructor(options: HITLWorkflowOptions);
+    /**
+     * Execute a workflow with human gates
+     */
+    executeWorkflow(sessionId: string, workflow: HITLWorkflowDefinition, initialContext: Record<string, unknown>): Promise<HITLWorkflowResult>;
+    /**
+     * Execute initial workflow steps
+     */
+    private executeInitialSteps;
+    /**
+     * Execute a human gate
+     */
+    private executeHumanGate;
+    /**
+     * Execute approval gate
+     */
+    private executeApprovalGate;
+    /**
+     * Execute edit gate
+     */
+    private executeEditGate;
+    /**
+     * Execute select gate
+     */
+    private executeSelectGate;
+    /**
+     * Execute custom gate
+     */
+    private executeCustomGate;
+    /**
+     * Execute branch steps
+     */
+    private executeBranchSteps;
+    /**
+     * Wait for interrupt response
+     */
+    private waitForResponse;
+    /**
+     * Interpolate input with context
+     */
+    private interpolateInput;
+    /**
+     * Get value from path
+     */
+    private getValueFromPath;
+    /**
+     * Get gate history for a session
+     */
+    getGateHistory(sessionId: string): HumanGateResult[];
+    /**
+     * Clear gate history
+     */
+    clearGateHistory(sessionId?: string): void;
+}
+/**
+ * Schema generation with human review
+ */
+export declare function createSchemaGenerationHITLWorkflow(complexity: 'simple' | 'medium' | 'complex'): HITLWorkflowDefinition;
+/**
+ * Multi-stage approval workflow
+ */
+export declare function createMultiStageApprovalWorkflow(stages: Array<{
+    name: string;
+    approver: string;
+}>): HITLWorkflowDefinition;
+export declare function createHITLWorkflowEngine(options: HITLWorkflowOptions): HITLWorkflowEngine;

package/dist/agent/index.d.ts

@@ -1,13 +1,14 @@
-export { E as EVENT_BUDGETS, S as SessionManager, f as SessionManagerOptions, g as Skill, F as SkillAgent, h as SkillAgentOptions, i as SkillAgentResult, j as SkillLoader, k as SkillMeta, l as SkillRefLoader, n as ToolTelemetry, W as WorkflowToolWrapper, p as WorkflowToolWrapperOptions, r as createEvalWorkflowWrapper, s as createSkillAgent, u as createWorkflowToolWrapper, w as getBudgetWarningMessage, x as getEventBudget, y as getInterruptConfig, B as resumeSkillAgent } from '../index-DZn69no8.js';
-export { Command } from '@langchain/langgraph';
-export { P as PersistenceMode, S as SessionMetadata, e as SessionRecord } from '../firestore-checkpointer-CkNKXoun.js';
-import '@almadar/llm';
-import '../orbital-subagent-BdFuf77p.js';
-import '@langchain/core/tools';
-import 'zod';
-import '../api-types-CXrq-fts.js';
-import '@almadar/core/types';
-import '@langchain/langgraph-checkpoint';
-import '@almadar/core';
-import '@langchain/core/messages';
-import '@langchain/core/runnables';
+/**
+ * Agent Module
+ *
+ * Agent factory, session management, event budgets, and interrupt configuration.
+ */
+export { createSkillAgent, resumeSkillAgent, Command, } from './skill-agent.js';
+export type { Skill, SkillLoader, SkillRefLoader, SkillAgentOptions, SkillAgentResult, SkillAgent, } from './skill-agent.js';
+export { SessionManager, } from './session-manager.js';
+export type { SessionMetadata, SessionRecord, PersistenceMode, SessionManagerOptions, } from './session-manager.js';
+export { EVENT_BUDGETS, getEventBudget, getBudgetWarningMessage, } from './event-budget.js';
+export { getInterruptConfig, } from './interrupt-config.js';
+export type { SkillMeta, } from './interrupt-config.js';
+export { createWorkflowToolWrapper, createEvalWorkflowWrapper, } from './workflow-tool-wrapper.js';
+export type { WorkflowToolWrapperOptions, ToolTelemetry, WorkflowToolWrapper, } from './workflow-tool-wrapper.js';