@almadar/agent 1.0.0

package/LICENSE

@@ -0,0 +1,72 @@
+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

package/dist/agent/index.d.ts

@@ -0,0 +1,250 @@
+import { LLMProvider } from '@almadar/llm';
+import { S as SubagentEventCallback, O as OrbitalCompleteCallback, D as DomainOrbitalCompleteCallback } from '../orbital-subagent-BsQBhKzi.js';
+import { BaseCheckpointSaver } from '@langchain/langgraph-checkpoint';
+import { P as PersistenceMode, b as FirestoreDb, d as SessionMetadata, e as SessionRecord } from '../firestore-checkpointer-DxbQ10ve.js';
+export { Command } from '@langchain/langgraph';
+import '@langchain/core/tools';
+import 'zod';
+import '../api-types-BW_58thJ.js';
+import '@langchain/core/runnables';
+
+/**
+ * Session Manager
+ *
+ * Unified session management API with pluggable persistence backends.
+ * Supports in-memory (development) and Firestore (production) backends.
+ */
+
+interface SessionManagerOptions {
+    /**
+     * Persistence mode.
+     * @default 'memory'
+     */
+    mode?: PersistenceMode;
+    /**
+     * Firestore database instance. Required when mode is 'firestore'.
+     */
+    firestoreDb?: FirestoreDb;
+}
+/**
+ * Unified session management for agent sessions.
+ *
+ * Handles both session metadata and LangGraph checkpointers.
+ */
+declare class SessionManager {
+    private mode;
+    private memoryBackend;
+    private memoryCheckpointers;
+    private firestoreCheckpointer;
+    private firestoreSessionStore;
+    constructor(options?: SessionManagerOptions);
+    /**
+     * Get the persistence mode.
+     */
+    getMode(): PersistenceMode;
+    /**
+     * Get or create a checkpointer for a session.
+     */
+    getCheckpointer(threadId: string): BaseCheckpointSaver<any>;
+    /**
+     * Store session metadata.
+     */
+    store(threadId: string, metadata: SessionMetadata): void;
+    /**
+     * Get session metadata (sync, memory only).
+     */
+    get(threadId: string): SessionMetadata | undefined;
+    /**
+     * Get session metadata (async, supports Firestore).
+     */
+    getAsync(threadId: string): Promise<SessionMetadata | undefined>;
+    /**
+     * Clear a session's checkpointer and metadata.
+     */
+    clear(threadId: string): boolean;
+    /**
+     * List all sessions (sync, memory only).
+     */
+    list(): SessionRecord[];
+    /**
+     * List all sessions (async, supports Firestore).
+     */
+    listAsync(): Promise<SessionRecord[]>;
+}
+
+/**
+ * Skill-Based DeepAgent Factory
+ *
+ * Creates DeepAgent instances that use skills as the primary prompt source.
+ * No custom system prompts - all agent behavior is defined through skills.
+ *
+ * Uses deepagents library primitives:
+ * - createDeepAgent() for agent creation
+ * - FilesystemBackend for file operations
+ *
+ * Skill loading is injected via SkillLoader functions, keeping this package
+ * independent of any specific skill registry location.
+ */
+
+/**
+ * Skill definition loaded by the consumer.
+ */
+interface Skill {
+    name: string;
+    description: string;
+    content: string;
+    allowedTools?: string[];
+    version?: string;
+    references: string[];
+    path?: string;
+}
+/**
+ * Function to load a skill by name.
+ */
+type SkillLoader = (name: string) => Skill | null;
+/**
+ * Function to load a skill reference by skill name and ref name.
+ */
+type SkillRefLoader = (skillName: string, refName: string) => string | null;
+/**
+ * Options for creating a skill agent.
+ */
+interface SkillAgentOptions {
+    /** Required: The skill(s) to use. Can be a single skill or array of skills. */
+    skill: string | string[];
+    /** Required: Working directory for the agent */
+    workDir: string;
+    /** Required: Function to load skills */
+    skillLoader: SkillLoader;
+    /** Optional: Function to load skill references */
+    skillRefLoader?: SkillRefLoader;
+    /** Optional: Thread ID for session continuity */
+    threadId?: string;
+    /** Optional: LLM provider */
+    provider?: LLMProvider;
+    /** Optional: Model name */
+    model?: string;
+    /** Optional: Enable verbose logging */
+    verbose?: boolean;
+    /** Optional: Disable human-in-the-loop interrupts (for eval/testing) */
+    noInterrupt?: boolean;
+    /** Optional: Callback for subagent events (orbital generation) */
+    onSubagentEvent?: SubagentEventCallback;
+    /** Optional: Session manager instance (shared across requests) */
+    sessionManager?: SessionManager;
+    /** Optional: Extracted requirements from analysis phase (for orbital skill) */
+    requirements?: {
+        entities?: string[];
+        states?: string[];
+        events?: string[];
+        guards?: string[];
+        pages?: string[];
+        effects?: string[];
+        rawRequirements?: string[];
+    };
+    /** Optional: GitHub integration configuration */
+    githubConfig?: {
+        /** GitHub personal access token */
+        token: string;
+        /** Repository owner (e.g., 'octocat') */
+        owner?: string;
+        /** Repository name (e.g., 'hello-world') */
+        repo?: string;
+    };
+}
+/**
+ * Result from creating a skill agent.
+ */
+interface SkillAgentResult {
+    /** The agent instance (from deepagents library) */
+    agent: any;
+    /** Thread ID for session resumption */
+    threadId: string;
+    /** The loaded skill(s) - primary skill when single, all skills when multiple */
+    skill: Skill;
+    /** All loaded skills (same as skill when single) */
+    skills: Skill[];
+    /** Working directory */
+    workDir: string;
+    /** Orbital tool setter for wiring SSE callback (if orbital tool enabled) */
+    setOrbitalEventCallback?: (callback: SubagentEventCallback) => void;
+    /** Orbital tool setter for wiring persistence callback */
+    setOrbitalCompleteCallback?: (callback: OrbitalCompleteCallback) => void;
+    /** Domain orbital callback for lean skill Firestore persistence */
+    setDomainCompleteCallback?: (callback: DomainOrbitalCompleteCallback) => void;
+}
+/**
+ * Create a skill-based DeepAgent.
+ *
+ * Uses the specified skill's content as the system prompt.
+ * When multiple skills are provided, the agent sees all skill descriptions
+ * and can choose the appropriate one based on the user's request.
+ *
+ * @throws Error if any skill is not found
+ */
+declare function createSkillAgent(options: SkillAgentOptions): Promise<SkillAgentResult>;
+/**
+ * Resume a skill agent session.
+ *
+ * Loads the skill from session metadata and creates agent with same threadId.
+ *
+ * @throws Error if session not found
+ */
+declare function resumeSkillAgent(threadId: string, options: {
+    verbose?: boolean;
+    noInterrupt?: boolean;
+    skillLoader: SkillLoader;
+    skillRefLoader?: SkillRefLoader;
+    sessionManager?: SessionManager;
+}): Promise<SkillAgentResult>;
+
+/**
+ * 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
+ */
+declare const EVENT_BUDGETS: Record<string, {
+    soft: number;
+    hard: number;
+}>;
+/**
+ * Get event budget for a skill.
+ */
+declare function getEventBudget(skillName: string): {
+    soft: number;
+    hard: number;
+};
+/**
+ * Generate a budget warning message to inject into the agent.
+ */
+declare function getBudgetWarningMessage(eventCount: number, budget: {
+    soft: number;
+    hard: number;
+}): string | null;
+
+/**
+ * Interrupt Configuration
+ *
+ * Human-in-the-loop configuration for agent tools.
+ */
+/**
+ * Skill metadata (minimal interface for interrupt config).
+ */
+interface SkillMeta {
+    name: string;
+    allowedTools?: string[];
+}
+/**
+ * Get interrupt configuration for a skill.
+ *
+ * Default: require approval for execute tool.
+ * Skills can override via frontmatter (future enhancement).
+ */
+declare function getInterruptConfig(_skill: SkillMeta): Record<string, boolean>;
+
+export { EVENT_BUDGETS, PersistenceMode, SessionManager, type SessionManagerOptions, SessionMetadata, SessionRecord, type Skill, type SkillAgentOptions, type SkillAgentResult, type SkillLoader, type SkillMeta, type SkillRefLoader, createSkillAgent, getBudgetWarningMessage, getEventBudget, getInterruptConfig, resumeSkillAgent };