@mamdouh-aboammar/agentic-workflow 1.2.0

package/src/hooks/types.ts

@@ -0,0 +1,61 @@
+/**
+ * Universal Agentic Hooks Framework (UAHF) — TypeScript Types & Data Models
+ * =========================================================================
+ * Canonical types for multi-platform hook events, verdicts, and policies in Bun/TypeScript.
+ */
+
+export type HookSource =
+  | 'claude'
+  | 'cursor'
+  | 'antigravity'
+  | 'codex'
+  | 'kimi'
+  | 'bash'
+  | 'terminal'
+  | 'homebrew'
+  | 'mcp'
+  | 'cli';
+
+export type HookType =
+  | 'pre_tool'
+  | 'post_tool'
+  | 'pre_command'
+  | 'post_command'
+  | 'session_start'
+  | 'session_end'
+  | 'error_trap';
+
+export type HookVerdict = 'allow' | 'block' | 'mutate' | 'warn' | 'ask_user';
+
+export interface HookEvent {
+  event_id: string;
+  source: HookSource;
+  hook_type: HookType;
+  timestamp: number;
+  tool_name?: string;
+  command?: string;
+  args?: Record<string, any>;
+  output?: any;
+  file_path?: string;
+  cwd?: string;
+  env?: Record<string, string>;
+  agent_id?: string;
+  metadata?: Record<string, any>;
+}
+
+export interface HookResult {
+  event_id: string;
+  verdict: HookVerdict;
+  message: string;
+  exit_code: number;
+  mutated_input?: Record<string, any>;
+  mutated_command?: string;
+  rule_id?: string;
+  metadata?: Record<string, any>;
+}
+
+export interface PolicyRule {
+  rule_id: string;
+  description: string;
+  evaluate(event: HookEvent): HookResult | null;
+}

package/src/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * AgenticWorkflow — Universal Autonomous Agentic Toolchain
+ * TypeScript Declaration File
+ */
+
+export * from './engine_ts/types.js';
+export * from './engine_ts/event-bus.js';
+export * from './engine_ts/queue.js';
+export * from './engine_ts/decider.js';
+export * from './engine_ts/verification-controller.js';
+export * from './engine_ts/worker.js';
+export * from './engine_ts/executor.js';
+export * from './engine_ts/skills-indexer.js';
+export * from './engine_ts/toon-adapter.js';
+
+export * from './hooks/types.js';
+export * from './hooks/dispatcher.js';
+export * from './hooks/session-end.js';
+export * from './hooks/policy-engine.js';
+
+export * from './integrations/registry.js';
+export * from './integrations/installer.js';
+export * from './integrations/lifecycle-director.js';
+
+export * from './system/types.js';
+export * from './system/updater.js';
+export * from './system/installer.js';
+export * from './system/refresher.js';
+export * from './system/doctor.js';
+export * from './system/health.js';
+export * from './system/dependencies.js';
+export * from './system/notifications.js';
+export * from './system/announcements.js';
+export * from './system/version-tracker.js';

package/src/index.ts

@@ -0,0 +1,23 @@
+/**
+ * AgenticWorkflow — Universal Autonomous Agentic Toolchain & Pluripotent Stem-Cell Framework
+ * 
+ * Top-level exports for TypeScript, Bun, and Node library consumers.
+ */
+
+// Event-driven engine, task queue, circuit breaker, verification controller
+export * from './engine_ts/index.js';
+
+// Universal Agentic Hooks Framework (UAHF)
+export * from './hooks/index.js';
+
+// Supportive Tools Subsystem (Ponytail, TOON, Fable, Caveman, LifecycleDirector)
+export * from './integrations/index.js';
+
+// Token-Oriented Object Notation (TOON v4.1) Adapter
+export * from './engine_ts/toon-adapter.js';
+
+// Agentic Skills Mesh & Universal Indexer
+export * from './engine_ts/skills-indexer.js';
+
+// Universal System Engines (Updater, Installer, Refresher, Doctor, Health, Dependencies, Notifications, Announcements, Version Tracker)
+export * from './system/index.ts';

package/src/integrations/index.ts

@@ -0,0 +1,7 @@
+/**
+ * src/integrations/index.ts — Unified export for Integrations subsystem
+ */
+
+export * from './registry.ts';
+export * from './installer.ts';
+export * from './lifecycle-director.ts';

package/src/integrations/installer.ts

@@ -0,0 +1,208 @@
+/**
+ * installer.ts — TypeScript/Bun Autonomous Supportive Tools Provisioner
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execSync } from 'node:child_process';
+import { IntegrationDefinition, IntegrationsRegistry, getDefaultRegistry } from './registry.ts';
+
+export interface InstallationStatus {
+  id: string;
+  name: string;
+  installed: boolean;
+  status: 'INSTALLED' | 'MISSING' | 'ERROR' | 'PROVISIONED';
+  details: string;
+  locations: string[];
+}
+
+export class IntegrationInstaller {
+  private projectDir: string;
+  private homeDir: string;
+  private targetSkillDirs: string[];
+
+  constructor(projectDir: string = '.') {
+    this.projectDir = path.resolve(projectDir);
+    this.homeDir = os.homedir();
+    this.targetSkillDirs = [
+      path.join(this.homeDir, '.gemini', 'config', 'skills'),
+      path.join(this.homeDir, '.claude', 'skills'),
+      path.join(this.homeDir, '.agents', 'skills'),
+      path.join(this.homeDir, '.codex', 'skills'),
+    ];
+  }
+
+  private findExistingSkillDir(skillName: string): string | null {
+    const searchDirs = [
+      ...this.targetSkillDirs,
+      path.join(this.homeDir, '.agent-kernel', 'plugins', skillName, 'skills', skillName),
+      path.join(this.homeDir, '.agent-kernel', 'plugins', skillName, 'skills'),
+      path.join(this.homeDir, '.claude', 'plugins', 'marketplaces', skillName),
+    ];
+
+    for (const dir of searchDirs) {
+      if (fs.existsSync(dir) && fs.statSync(dir).isDirectory()) {
+        const skillFile = path.join(dir, 'SKILL.md');
+        if (fs.existsSync(skillFile)) {
+          return dir;
+        }
+        const childDir = path.join(dir, skillName);
+        if (fs.existsSync(childDir) && fs.existsSync(path.join(childDir, 'SKILL.md'))) {
+          return childDir;
+        }
+      }
+    }
+    return null;
+  }
+
+  public checkStatus(item: IntegrationDefinition): InstallationStatus {
+    const detectedLocations: string[] = [];
+
+    // 1. Skill directories
+    const skillNames: string[] = item.install?.skill_names || [item.id];
+    for (const sname of skillNames) {
+      for (const base of this.targetSkillDirs) {
+        const candidate = path.join(base, sname);
+        if (fs.existsSync(candidate)) {
+          detectedLocations.push(candidate);
+        }
+      }
+    }
+
+    // 2. npm / bun package
+    const npmPkg = item.detection?.npm_package;
+    if (npmPkg) {
+      const pkgPath = path.join(this.projectDir, 'node_modules', npmPkg);
+      if (fs.existsSync(pkgPath)) {
+        detectedLocations.push(`node_modules/${npmPkg}`);
+      }
+    }
+
+    // 3. state dir
+    const stateDir = item.detection?.state_dir;
+    if (stateDir) {
+      const fullState = path.join(this.projectDir, stateDir);
+      if (fs.existsSync(fullState)) {
+        detectedLocations.push(stateDir);
+      }
+    }
+
+    const isInstalled = detectedLocations.length > 0;
+    return {
+      id: item.id,
+      name: item.name,
+      installed: isInstalled,
+      status: isInstalled ? 'INSTALLED' : 'MISSING',
+      details: isInstalled ? `Active at ${detectedLocations.length} location(s)` : 'Not found in environment paths',
+      locations: detectedLocations
+    };
+  }
+
+  public provision(item: IntegrationDefinition, synchronizeAll: boolean = true): InstallationStatus {
+    const strategy = item.install?.strategy || 'skill';
+    const createdLocations: string[] = [];
+
+    try {
+      if (strategy === 'skill' || strategy === 'hybrid') {
+        const skillNames: string[] = item.install?.skill_names || [item.id];
+        for (const sname of skillNames) {
+          const existing = this.findExistingSkillDir(sname);
+          if (existing) {
+            for (const targetDir of this.targetSkillDirs) {
+              const dest = path.join(targetDir, sname);
+              if (!fs.existsSync(dest)) {
+                fs.mkdirSync(targetDir, { recursive: true });
+                try {
+                  fs.symlinkSync(existing, dest);
+                  createdLocations.push(dest);
+                } catch {
+                  fs.cpSync(existing, dest, { recursive: true });
+                  createdLocations.push(dest);
+                }
+              }
+            }
+          } else {
+            const fallbackGit = item.install?.fallback_git;
+            if (fallbackGit) {
+              const primaryTarget = path.join(this.homeDir, '.agents', 'skills', sname);
+              fs.mkdirSync(path.dirname(primaryTarget), { recursive: true });
+              try {
+                execSync(`git clone --depth 1 "${fallbackGit}" "${primaryTarget}"`, { stdio: 'pipe', timeout: 30000 });
+                createdLocations.push(primaryTarget);
+                for (const targetDir of this.targetSkillDirs) {
+                  const dest = path.join(targetDir, sname);
+                  if (!fs.existsSync(dest)) {
+                    fs.mkdirSync(targetDir, { recursive: true });
+                    try {
+                      fs.symlinkSync(primaryTarget, dest);
+                      createdLocations.push(dest);
+                    } catch {
+                      fs.cpSync(primaryTarget, dest, { recursive: true });
+                      createdLocations.push(dest);
+                    }
+                  }
+                }
+              } catch {
+                // Ignore clone errors
+              }
+            }
+          }
+        }
+      }
+
+      if (strategy === 'package' || strategy === 'hybrid') {
+        const bunPkg = item.install?.bun_package;
+        const npmPkg = item.detection?.npm_package;
+        if (bunPkg && (!npmPkg || !fs.existsSync(path.join(this.projectDir, 'node_modules', npmPkg)))) {
+          try {
+            execSync(`bun add "${bunPkg}"`, { cwd: this.projectDir, stdio: 'pipe', timeout: 30000 });
+            createdLocations.push(`bun:${bunPkg}`);
+          } catch {
+            // Ignore if bun fails
+          }
+        }
+      }
+
+      const postStatus = this.checkStatus(item);
+      if (postStatus.installed || createdLocations.length > 0) {
+        return {
+          id: item.id,
+          name: item.name,
+          installed: true,
+          status: createdLocations.length > 0 ? 'PROVISIONED' : postStatus.status,
+          details: `Active at ${postStatus.locations.length} location(s)` + (createdLocations.length > 0 ? ` (${createdLocations.length} newly synced)` : ''),
+          locations: postStatus.locations
+        };
+      }
+
+      return {
+        id: item.id,
+        name: item.name,
+        installed: false,
+        status: 'ERROR',
+        details: 'Provisioning completed without active targets confirmed',
+        locations: []
+      };
+    } catch (err: any) {
+      return {
+        id: item.id,
+        name: item.name,
+        installed: false,
+        status: 'ERROR',
+        details: `Provisioning error: ${err?.message || String(err)}`,
+        locations: []
+      };
+    }
+  }
+
+  public provisionAll(registry?: IntegrationsRegistry): InstallationStatus[] {
+    const reg = registry || getDefaultRegistry(this.projectDir);
+    return reg.listAll().map(item => this.provision(item, true));
+  }
+
+  public checkAll(registry?: IntegrationsRegistry): InstallationStatus[] {
+    const reg = registry || getDefaultRegistry(this.projectDir);
+    return reg.listAll().map(item => this.checkStatus(item));
+  }
+}

package/src/integrations/lifecycle-director.ts

@@ -0,0 +1,139 @@
+/**
+ * lifecycle-director.ts — TypeScript Sequential Operational Lifecycle Director
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { IntegrationsRegistry, getDefaultRegistry } from './registry.ts';
+
+export interface PhaseDirectives {
+  phase: string;
+  activeIntegrations: string[];
+  systemPromptOverlay: string;
+  rules: string[];
+  toolsEngaged: string[];
+}
+
+export class LifecycleDirector {
+  private projectDir: string;
+  private registry: IntegrationsRegistry;
+
+  constructor(projectDir: string = '.', registry?: IntegrationsRegistry) {
+    this.projectDir = path.resolve(projectDir);
+    this.registry = registry || getDefaultRegistry(this.projectDir);
+  }
+
+  public getPhaseDirectives(phase: string): PhaseDirectives {
+    const norm = phase.toLowerCase().trim();
+    const matched = this.registry.getForPhase(norm);
+
+    const activeNames = matched.map(m => m.name);
+    const toolsEngaged = matched.map(m => m.id);
+    const rules: string[] = [];
+    const sections: string[] = [];
+
+    // Continuous protocols (TOON & Caveman)
+    const toonItem = this.registry.get('toon');
+    if (toonItem && toonItem.directives?.continuous) {
+      sections.push(`### [Continuous Protocol] TOON v4.1 Serialization\n${toonItem.directives.continuous}`);
+      rules.push('Format all structured datasets and task tables in TOON syntax to conserve 30-60% tokens.');
+    }
+
+    const cavemanItem = this.registry.get('caveman');
+    if (cavemanItem && cavemanItem.directives?.continuous) {
+      sections.push(`### [Communication Protocol] Caveman Terse Mode\n${cavemanItem.directives.continuous}`);
+      rules.push('Eliminate pleasantries in logs and intermediate agent thought; keep code, paths, and errors verbatim.');
+    }
+
+    for (const item of matched) {
+      if (item.directives?.[norm]) {
+        sections.push(`### [${item.name}] Phase Directives (${norm})\n${item.directives[norm]}`);
+        rules.push(`[${item.name}] ${item.directives[norm]}`);
+      }
+    }
+
+    let overview = `## ⚡ Sequential Lifecycle Directive: ${norm.toUpperCase()} Phase`;
+    if (norm === 'planning') {
+      overview = `## 🧭 Sequential Lifecycle Directive: Phase 2 — Architecture & Planning
+Enforce Ponytail YAGNI Ladder (Rungs 1-3):
+1. Question whether every proposed component needs to exist.
+2. Reuse existing helpers and stdlib before creating new abstractions.
+3. Formulate verifiable Fable contracts with concrete success criteria.
+4. Compile and validate OmniSkill SkillSpec contracts and dynamic DAG execution paths.`;
+    } else if (norm === 'implementation') {
+      overview = `## 🔨 Sequential Lifecycle Directive: Phase 3 — Production Implementation
+1. Shortest working diff wins. Minimum code that works (Ponytail Rungs 4-7).
+2. Fix root causes across callers/callees, not symptoms.
+3. Fable Circuit Breaker active: halt speculative edits if failure streak >= 2.
+4. Follow OmniSkill progressive disclosure: frontmatter <=1024 chars, core SKILL.md, references/, scripts/.`;
+    } else if (norm === 'verification') {
+      overview = `## 🛡️ Sequential Lifecycle Directive: Phase 4 — Verification & Quality Gates
+1. Run Clean Code Guard (SOLID, 24 Imperatives).
+2. Perform Ponytail anti-debt check against over-engineering.
+3. Pass L0 Anti-Skip, L1 Verification, L1.5 pACS (min score >= 70), and L2 Review.
+4. Enforce OmniSkill 4-Layer Validation (Artifact, Discovery, Behavior, Portability).`;
+    } else if (norm === 'handoff') {
+      overview = `## 🏁 Sequential Lifecycle Directive: Phase 5 — Handoff & Continuation
+1. Compact session into durable continuation state (.fable/state.json, PROGRESS.md).
+2. Archive run traces and ledgers in high-density TOON format.`;
+    }
+
+    const systemPromptOverlay = `${overview}\n\n` + sections.join('\n\n');
+
+    return {
+      phase: norm,
+      activeIntegrations: activeNames,
+      systemPromptOverlay,
+      rules,
+      toolsEngaged
+    };
+  }
+
+  public executePrePhaseGuards(phase: string, context: Record<string, any> = {}): { allowed: boolean; warnings: string[]; actionsTaken: string[] } {
+    const norm = phase.toLowerCase().trim();
+    const warnings: string[] = [];
+    const actionsTaken: string[] = [];
+    let allowed = true;
+
+    if (norm === 'implementation') {
+      const streak = context.failure_streak || 0;
+      if (streak >= 2) {
+        allowed = false;
+        warnings.push(`Fable Circuit Breaker TRIPPED: failure streak (${streak}) >= 2. Halting to prevent thrashing.`);
+        actionsTaken.push('trip_circuit_breaker');
+      }
+    }
+
+    if (norm === 'planning') {
+      actionsTaken.push('enforce_ponytail_yagni_gate');
+    }
+
+    return { allowed, warnings, actionsTaken };
+  }
+
+  public executePostPhaseActions(phase: string, context: Record<string, any> = {}): { success: boolean; artifactsGenerated: string[] } {
+    const norm = phase.toLowerCase().trim();
+    const artifactsGenerated: string[] = [];
+
+    if (norm === 'handoff') {
+      const fableDir = path.join(this.projectDir, '.fable');
+      fs.mkdirSync(fableDir, { recursive: true });
+      const stateFile = path.join(fableDir, 'state.json');
+      const progressFile = path.join(fableDir, 'PROGRESS.md');
+
+      const payload = {
+        trace_id: context.trace_id || `trace_${Date.now()}`,
+        timestamp: new Date().toISOString(),
+        status: 'COMPLETED',
+        next_action: context.next_action || 'All workflow stages verified cleanly.'
+      };
+
+      fs.writeFileSync(stateFile, JSON.stringify(payload, null, 2), 'utf-8');
+      fs.writeFileSync(progressFile, `# Fable Continuation Progress\n\n- Timestamp: ${payload.timestamp}\n- Trace: \`${payload.trace_id}\`\n- Next Action: ${payload.next_action}\n`, 'utf-8');
+
+      artifactsGenerated.push(stateFile, progressFile);
+    }
+
+    return { success: true, artifactsGenerated };
+  }
+}

package/src/integrations/registry.ts

@@ -0,0 +1,82 @@
+/**
+ * registry.ts — TypeScript Integrations Registry & Manifest Manager
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export interface IntegrationDefinition {
+  id: string;
+  name: string;
+  repo: string;
+  description: string;
+  category: string;
+  lifecycle_phases: string[];
+  install: Record<string, any>;
+  detection: Record<string, any>;
+  directives: Record<string, string>;
+}
+
+export class IntegrationsRegistry {
+  private integrations: Map<string, IntegrationDefinition> = new Map();
+  private manifestPath: string | null = null;
+
+  constructor(manifestPath?: string) {
+    if (manifestPath && fs.existsSync(manifestPath)) {
+      this.loadFromFile(manifestPath);
+    }
+  }
+
+  public loadFromFile(filePath: string): void {
+    this.manifestPath = path.resolve(filePath);
+    const content = fs.readFileSync(this.manifestPath, 'utf-8');
+    const data = JSON.parse(content);
+    this.integrations.clear();
+    for (const item of data.integrations || []) {
+      this.integrations.set(item.id, item);
+    }
+  }
+
+  public saveToFile(targetPath?: string): void {
+    const dest = targetPath || this.manifestPath;
+    if (!dest) {
+      throw new Error("No target path specified for saving integrations manifest.");
+    }
+    const data = {
+      version: "1.0.0",
+      description: "Declarative registry of supportive tools, frameworks, and agentic skills for AgenticWorkflow",
+      integrations: Array.from(this.integrations.values())
+    };
+    fs.writeFileSync(dest, JSON.stringify(data, null, 2), 'utf-8');
+  }
+
+  public register(item: IntegrationDefinition): void {
+    this.integrations.set(item.id, item);
+  }
+
+  public get(id: string): IntegrationDefinition | undefined {
+    return this.integrations.get(id);
+  }
+
+  public listAll(): IntegrationDefinition[] {
+    return Array.from(this.integrations.values());
+  }
+
+  public getForPhase(phase: string): IntegrationDefinition[] {
+    const norm = phase.toLowerCase().trim();
+    return this.listAll().filter(item => 
+      item.lifecycle_phases.includes("continuous") || item.lifecycle_phases.includes(norm)
+    );
+  }
+}
+
+export function getDefaultRegistry(projectDir: string = "."): IntegrationsRegistry {
+  let manifestPath = path.join(path.resolve(projectDir), "integrations.json");
+  if (!fs.existsSync(manifestPath)) {
+    const rootFallback = path.resolve(__dirname, "..", "..", "integrations.json");
+    if (fs.existsSync(rootFallback)) {
+      manifestPath = rootFallback;
+    }
+  }
+  return new IntegrationsRegistry(manifestPath);
+}