@almadar/agent 1.2.1 → 1.3.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

@@ -1,8 +1,8 @@
-export { E as EVENT_BUDGETS, S as SessionManager, e as SessionManagerOptions, f as Skill, g as SkillAgentOptions, h as SkillAgentResult, i as SkillLoader, j as SkillMeta, k as SkillRefLoader, m as createSkillAgent, p as getBudgetWarningMessage, q as getEventBudget, r as getInterruptConfig, t as resumeSkillAgent } from '../index-D-Ahuo6F.js';
+export { E as EVENT_BUDGETS, S as SessionManager, e as SessionManagerOptions, f as Skill, g as SkillAgentOptions, h as SkillAgentResult, i as SkillLoader, j as SkillMeta, k as SkillRefLoader, m as createSkillAgent, p as getBudgetWarningMessage, q as getEventBudget, r as getInterruptConfig, t as resumeSkillAgent } from '../index-DNe7JzkE.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-cNfTLdXQ.js';
+import '../orbital-subagent-CiOIu9Ax.js';
 import '@langchain/core/tools';
 import 'zod';
 import '../api-types-BW_58thJ.js';

package/dist/agent/index.js

@@ -13,8 +13,7 @@ import * as fs4 from 'fs/promises';
 import * as domain_language_star from '@almadar/core/domain-language';
 import * as fs3 from 'fs';
 import crypto, { randomUUID } from 'crypto';
-import { getFullOrbitalPrompt, generateKflowDesignSkill, getRequirementsTraitPrompt, getKeyBehaviorsReference, getSExprQuickRef, getCommonErrorsSection, getArchitectureSection } from '@almadar/skills';
-import { formatRecommendationsForPrompt, buildRecommendationContext, recommendPatterns } from '@almadar/patterns';
+import { getFullOrbitalPrompt, getRequirementsTraitPrompt, getKeyBehaviorsReference, getSExprQuickRef, getCommonErrorsSection, getArchitectureSection } from '@almadar/skills';
 import { GitHubIntegration } from '@almadar/integrations';
 import { BaseCheckpointSaver } from '@langchain/langgraph-checkpoint';
 
@@ -1051,6 +1050,77 @@ npx kflow domain:validate input.orb --verbose
 
 // src/tools/finish-task.ts
 var execAsync2 = promisify(exec);
+var PROP_CORRECTIONS = {
+  onSubmit: "submitEvent",
+  onCancel: "cancelEvent",
+  headerActions: "actions",
+  loading: "isLoading",
+  fieldNames: "fields"
+};
+function autoCorrectProps(schema) {
+  let corrections = 0;
+  JSON.stringify(schema);
+  function walkAndFix(obj) {
+    if (Array.isArray(obj)) {
+      return obj.map(walkAndFix);
+    }
+    if (obj && typeof obj === "object") {
+      const result = {};
+      for (const [key, value] of Object.entries(obj)) {
+        if (key in PROP_CORRECTIONS) {
+          result[PROP_CORRECTIONS[key]] = walkAndFix(value);
+          corrections++;
+        } else {
+          result[key] = walkAndFix(value);
+        }
+      }
+      return result;
+    }
+    return obj;
+  }
+  const fixed = walkAndFix(schema);
+  Object.assign(schema, fixed);
+  return corrections;
+}
+function checkCompositionQuality(schema) {
+  const warnings = [];
+  const orbitals = schema.orbitals;
+  if (!Array.isArray(orbitals)) return warnings;
+  for (const orbital of orbitals) {
+    const orbObj = orbital;
+    const traits = orbObj.traits;
+    if (!Array.isArray(traits)) continue;
+    for (const trait of traits) {
+      const traitObj = trait;
+      const transitions = traitObj.stateMachine?.transitions;
+      if (!Array.isArray(transitions)) continue;
+      for (const transition of transitions) {
+        const trans = transition;
+        if (trans.event !== "INIT") continue;
+        const effects = trans.effects;
+        if (!Array.isArray(effects)) continue;
+        const mainRenderUIs = effects.filter(
+          (e) => Array.isArray(e) && e[0] === "render-ui" && e[1] === "main"
+        );
+        if (mainRenderUIs.length > 1) {
+          warnings.push(
+            `\u26A0\uFE0F ${orbObj.name}/${traitObj.name} INIT has ${mainRenderUIs.length} flat render-ui calls to main. Should be a single composed stack with children.`
+          );
+        }
+        if (mainRenderUIs.length === 1) {
+          const renderPayload = mainRenderUIs[0];
+          const payload = renderPayload[2];
+          if (payload && payload.type !== "stack" && !payload.children) {
+            warnings.push(
+              `\u26A0\uFE0F ${orbObj.name}/${traitObj.name} INIT renders a single flat ${payload.type} to main. Should be a composed stack with header, metrics, and data sections.`
+            );
+          }
+        }
+      }
+    }
+  }
+  return warnings;
+}
 async function collectOrbitalsFromDir(workDir) {
   const orbitalsDir = path.join(workDir, ".orbitals");
   try {
@@ -1105,6 +1175,8 @@ function createFinishTaskTool(workDir) {
       let stats = null;
       let validationResult = null;
       let source = null;
+      let propCorrections = 0;
+      let compositionWarnings = [];
       if (workDir) {
         const orbitals = await collectOrbitalsFromDir(workDir);
         if (orbitals.length > 0) {
@@ -1149,6 +1221,10 @@ function createFinishTaskTool(workDir) {
           } catch {
           }
         }
+        if (combinedSchema) {
+          propCorrections = autoCorrectProps(combinedSchema);
+          compositionWarnings = checkCompositionQuality(combinedSchema);
+        }
         if (combinedSchema) {
           const schemaPath = path.join(workDir, "schema.json");
           await fs4.writeFile(schemaPath, JSON.stringify(combinedSchema, null, 2));
@@ -1168,6 +1244,10 @@ function createFinishTaskTool(workDir) {
           errorCount: validationResult.errors?.length || 0,
           warningCount: validationResult.warnings?.length || 0
         } : void 0,
+        designQuality: {
+          propCorrections: propCorrections || 0,
+          compositionWarnings: compositionWarnings || []
+        },
         schemaPath: combinedSchema ? path.join(workDir, "schema.json") : input.schemaPath,
         nextAction: "NONE - Task is complete. Output a brief success message to the user."
       };
@@ -2328,273 +2408,6 @@ function createSchemaChunkingTools(workDir) {
     applyChunk: createApplyChunkTool(workDir)
   };
 }
-var designCache = /* @__PURE__ */ new Map();
-var CACHE_TTL_MS2 = 24 * 60 * 60 * 1e3;
-var CACHE_VERSION2 = 1;
-function generateFingerprint2(input) {
-  const normalized = JSON.stringify({
-    version: CACHE_VERSION2,
-    ...input
-  });
-  return crypto.createHash("sha256").update(normalized).digest("hex").slice(0, 16);
-}
-function getCached2(fingerprint) {
-  const entry = designCache.get(fingerprint);
-  if (!entry) return null;
-  if (Date.now() - entry.timestamp > CACHE_TTL_MS2) {
-    designCache.delete(fingerprint);
-    return null;
-  }
-  return entry;
-}
-var STATIC_DESIGN_PROMPT = null;
-function getDesignSystemPrompt() {
-  if (!STATIC_DESIGN_PROMPT) {
-    const skill = generateKflowDesignSkill();
-    STATIC_DESIGN_PROMPT = skill.content;
-  }
-  return STATIC_DESIGN_PROMPT;
-}
-function getPatternRecommendations(input) {
-  const recContext = buildRecommendationContext({
-    state: input.from,
-    event: input.event,
-    slot: input.slot,
-    domainCategory: input.domainCategory,
-    entityFields: input.entityFields
-  });
-  return recommendPatterns(recContext, 8);
-}
-function buildDesignUserPrompt(input) {
-  const fieldList = input.entityFields.map((f) => {
-    let desc = `  - ${f.name}: ${f.type}`;
-    if (f.values) desc += ` (values: ${f.values.join(", ")})`;
-    return desc;
-  }).join("\n");
-  const hints = [];
-  if (input.designStyle) hints.push(`Style: ${input.designStyle}`);
-  if (input.flowPattern) hints.push(`Flow: ${input.flowPattern}`);
-  if (input.listPattern) hints.push(`List: ${input.listPattern}`);
-  if (input.formPattern) hints.push(`Form: ${input.formPattern}`);
-  if (input.detailPattern) hints.push(`Detail: ${input.detailPattern}`);
-  const vocab = input.vocabulary ? Object.entries(input.vocabulary).map(([k, v]) => `  ${k} \u2192 "${v}"`).join("\n") : "";
-  return `Design render-ui effects for this transition:
-
-## Transition
-- **From**: ${input.from}
-- **To**: ${input.to}
-- **Event**: ${input.event}
-- **Slot**: ${input.slot}
-
-## Entity: ${input.entityName}
-${fieldList}
-
-## Domain
-- **Category**: ${input.domainCategory || "business"}
-${vocab ? `- **Vocabulary**:
-${vocab}` : ""}
-${hints.length > 0 ? `- **Design Hints**: ${hints.join(", ")}` : ""}
-
-${input.recommendationsSection || ""}
-
-${input.existingEffects ? `## Existing Effects (enhance these)
-\`\`\`json
-${JSON.stringify(input.existingEffects, null, 2)}
-\`\`\`` : ""}
-
-Return ONLY the JSON array of render-ui effect tuples.`;
-}
-var DesignTransitionSchema = z.object({
-  from: z.string().describe('Source state name (e.g., "Browsing")'),
-  to: z.string().describe('Target state name (e.g., "Browsing" for self-loop, "Creating" for transition)'),
-  event: z.string().describe('Event name (e.g., "INIT", "CREATE", "VIEW", "EDIT", "DELETE", "SAVE", "CANCEL")'),
-  slot: z.string().describe('UI slot to render into: "main", "modal", "drawer", "sidebar", "overlay"'),
-  entityName: z.string().describe('Entity name (e.g., "Task", "Order")'),
-  entityFields: z.array(z.object({
-    name: z.string(),
-    type: z.string(),
-    values: z.array(z.string()).optional()
-  })).describe("Entity fields with types and optional enum values"),
-  domainCategory: AgentDomainCategorySchema.optional().describe("Domain category for pattern selection"),
-  vocabulary: z.record(z.string(), z.string()).optional().describe('Domain vocabulary mapping (e.g., { "create": "Place Order", "item": "Order" })'),
-  designStyle: z.enum(["minimal", "modern", "playful", "data-driven", "immersive"]).optional().describe("Visual style hint"),
-  flowPattern: z.enum(["hub-spoke", "master-detail", "crud-cycle", "linear", "role-based"]).optional().describe("Application flow pattern"),
-  listPattern: z.enum(["entity-table", "entity-cards", "entity-list"]).optional().describe("Preferred list pattern"),
-  formPattern: z.enum(["modal", "drawer", "page"]).optional().describe("Preferred form pattern"),
-  detailPattern: z.enum(["drawer", "page", "split"]).optional().describe("Preferred detail view pattern"),
-  existingEffects: z.array(z.any()).optional().describe("Existing render-ui effects to enhance (for refinement passes)")
-});
-function createDesignTransitionTool(options = {}) {
-  let eventCallback = options.onEvent;
-  const setEventCallback = (callback) => {
-    eventCallback = callback;
-  };
-  const emitEvent = (transitionId, type, data) => {
-    if (eventCallback) {
-      eventCallback(transitionId, {
-        type,
-        data,
-        timestamp: Date.now()
-      });
-    }
-  };
-  const designTransitionTool = tool(
-    async (input) => {
-      const transitionId = `${input.entityName}:${input.from}->${input.to}:${input.event}`;
-      const fingerprint = generateFingerprint2({
-        from: input.from,
-        to: input.to,
-        event: input.event,
-        slot: input.slot,
-        entityName: input.entityName,
-        entityFields: input.entityFields,
-        domainCategory: input.domainCategory,
-        designStyle: input.designStyle,
-        flowPattern: input.flowPattern,
-        listPattern: input.listPattern
-      });
-      try {
-        emitEvent(transitionId, "message", {
-          content: `Designing UI for ${transitionId}`,
-          role: "assistant",
-          isComplete: false
-        });
-        const cached = getCached2(fingerprint);
-        if (cached) {
-          emitEvent(transitionId, "generation_log", {
-            level: "info",
-            message: `Design cache HIT for ${transitionId}`,
-            data: { fingerprint }
-          });
-          return JSON.stringify({
-            success: true,
-            transitionId,
-            effects: cached.effects,
-            cached: true,
-            usage: cached.usage
-          });
-        }
-        const recommendations = getPatternRecommendations(input);
-        const recommendationsSection = formatRecommendationsForPrompt(recommendations);
-        const systemPrompt = getDesignSystemPrompt();
-        const userPrompt = buildDesignUserPrompt({
-          ...input,
-          recommendationsSection
-        });
-        emitEvent(transitionId, "tool_call", {
-          tool: "llm_design_transition",
-          args: {
-            transition: transitionId,
-            slot: input.slot,
-            domain: input.domainCategory
-          }
-        });
-        const client = new LLMClient({
-          provider: "anthropic",
-          model: "claude-sonnet-4-20250514",
-          temperature: 0.1
-          // Slight creativity for design
-        });
-        const response = await client.callWithCache({
-          systemPrompt: "",
-          systemBlocks: [{
-            type: "text",
-            text: systemPrompt,
-            cache_control: { type: "ephemeral" }
-          }],
-          userPrompt,
-          maxTokens: 4096,
-          rawText: true
-        });
-        const rawText = (response.raw || String(response.data) || "").trim();
-        let effects;
-        try {
-          const jsonText = rawText.replace(/^```(?:json)?\n?/m, "").replace(/\n?```$/m, "").trim();
-          effects = JSON.parse(jsonText);
-          if (!Array.isArray(effects)) {
-            effects = [effects];
-          }
-        } catch {
-          return JSON.stringify({
-            success: false,
-            transitionId,
-            error: "Failed to parse design output as JSON",
-            rawOutput: rawText
-          });
-        }
-        const usage = {
-          inputTokens: response.usage?.promptTokens || 0,
-          outputTokens: response.usage?.completionTokens || 0,
-          totalTokens: response.usage?.totalTokens || 0
-        };
-        designCache.set(fingerprint, {
-          effects,
-          timestamp: Date.now(),
-          usage
-        });
-        emitEvent(transitionId, "tool_result", {
-          tool: "llm_design_transition",
-          result: { fingerprint, effectCount: effects.length, usage },
-          success: true
-        });
-        emitEvent(transitionId, "message", {
-          content: `Designed ${effects.length} effect(s) for ${transitionId} (${usage.totalTokens} tokens)`,
-          role: "assistant",
-          isComplete: true
-        });
-        return JSON.stringify({
-          success: true,
-          transitionId,
-          effects,
-          cached: false,
-          usage,
-          recommendedPatterns: recommendations.map((r) => r.pattern)
-        });
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        emitEvent(transitionId, "error", {
-          error: errorMessage,
-          code: "DESIGN_TRANSITION_ERROR"
-        });
-        return JSON.stringify({
-          success: false,
-          transitionId,
-          error: errorMessage
-        });
-      }
-    },
-    {
-      name: "design_transition",
-      description: `Design rich render-ui effects for a single orbital transition.
-
-Takes the transition context (from/to state, event, entity, domain) and produces
-polished render-ui effects using the full pattern catalog.
-
-USE THIS TOOL WHEN:
-- Generating INIT transitions (always compose header + stats + content)
-- Generating CREATE/EDIT transitions (form with proper fields)
-- Generating VIEW transitions (detail with tabs for related entities)
-- Enhancing existing render-ui effects that are too basic
-
-The tool uses a specialized design skill with pattern catalog, layout composition,
-and domain-aware pattern selection to produce rich UI.
-
-RETURNS: { success, effects: [["render-ui", slot, config], ...], transitionId, usage }
-
-The effects array contains ONLY render-ui tuples. Non-UI effects (persist, emit, set)
-are NOT included \u2014 you must preserve those from the original transition.
-
-INTEGRATION: After calling this tool, use extract_chunk to get the orbital,
-replace the render-ui effects in the target transition (keep persist/emit/set effects),
-then apply_chunk to merge back into schema.json.`,
-      schema: DesignTransitionSchema
-    }
-  );
-  return {
-    tool: designTransitionTool,
-    setEventCallback
-  };
-}
 function createGitHubTools(config) {
   const { token, owner = "", repo = "", workDir } = config;
   const integrationConfig = {
@@ -3814,11 +3627,9 @@ ${skillContents}`;
   const validateSchemaTool = createValidateSchemaTool(workDir);
   const ORBITAL_SKILLS = ["kflow-orbitals", "kflow-orbital-games", "kflow-orbital-fixing"];
   const LEAN_SKILLS = ["kflow-lean-orbitals", "kflow-lean-fixing"];
-  const DESIGN_SKILLS = ["kflow-design", "kflow-lean-design"];
   const isOrbitalSkill = primarySkill.name === "kflow-orbitals";
   const isLeanSkill = LEAN_SKILLS.includes(primarySkill.name);
-  const isDesignSkill = DESIGN_SKILLS.includes(primarySkill.name);
-  const needsChunkingTools = ORBITAL_SKILLS.includes(primarySkill.name) || isDesignSkill;
+  const needsChunkingTools = ORBITAL_SKILLS.includes(primarySkill.name);
   let orbitalTool;
   let setOrbitalEventCallback;
   let setOrbitalCompleteCallback;
@@ -3844,11 +3655,6 @@ ${skillContents}`;
       console.log(`[SkillAgent] Domain orbital tools enabled for ${primarySkill.name} skill`);
     }
   }
-  const needsDesignTool = isDesignSkill || ORBITAL_SKILLS.includes(primarySkill.name);
-  const designTool = needsDesignTool ? createDesignTransitionTool() : null;
-  if (designTool && verbose) {
-    console.log(`[SkillAgent] Design transition tool enabled for ${primarySkill.name} skill`);
-  }
   const githubTools = options.githubConfig ? createGitHubToolsArray({
     token: options.githubConfig.token,
     owner: options.githubConfig.owner,
@@ -3872,7 +3678,6 @@ ${skillContents}`;
       chunkingTools.extractChunk,
       chunkingTools.applyChunk
     ] : [],
-    ...designTool ? [designTool.tool] : [],
     ...githubTools || []
   ];
   const checkpointer = sessions.getCheckpointer(threadId);