@flomatai/core 0.1.0

package/src/strategies/plan-and-execute.ts

@@ -0,0 +1,268 @@
+/**
+ * Plan-and-Execute strategy — LLM creates a plan upfront, then executes it.
+ *
+ * 1. LLM receives goal + skill catalog → produces ordered execution plan
+ * 2. Each planned step is executed
+ * 3. Optional: re-plan after each step based on actual outputs
+ */
+
+import type { Skill } from '../skill.js';
+import type { Strategy, AgentContext, AgentResult, AgentTraceEntry } from './types.js';
+
+interface PlanStep {
+  step_name: string;
+  skill: string;
+  input_description: string;
+  expected_output: string;
+  depends_on: string[];
+}
+
+interface Plan {
+  reasoning: string;
+  steps: PlanStep[];
+}
+
+export interface PlanAndExecuteOptions {
+  /** Re-plan after each step based on actual output (default: false). */
+  replanAfterEachStep?: boolean;
+  /** Max number of re-plans allowed (default: 3). */
+  maxReplans?: number;
+  /** Custom planning prompt override. Receives skill catalog + goal. */
+  planPromptTemplate?: string;
+}
+
+export class PlanAndExecuteStrategy implements Strategy {
+  constructor(private options: PlanAndExecuteOptions = {}) {}
+
+  async execute(
+    skills: Skill[],
+    input: unknown,
+    ctx: AgentContext,
+  ): Promise<AgentResult> {
+    const trace: AgentTraceEntry[] = [];
+    const startMs = Date.now();
+    const results = new Map<string, unknown>();
+    let replanCount = 0;
+    const maxReplans = this.options.maxReplans ?? 3;
+
+    // ── Phase 1: Plan ──────────────────────────────────────────────────────
+    let plan = await this.createPlan(skills, input, results, ctx);
+    trace.push({
+      type: 'plan',
+      content: plan,
+      timestamp: new Date().toISOString(),
+    });
+    ctx.logger.debug(`[plan-and-execute] Plan created: ${plan.steps.length} steps`);
+
+    // ── Phase 2: Execute ───────────────────────────────────────────────────
+    const sortedSteps = this.topologicalSort(plan.steps);
+
+    for (const planStep of sortedSteps) {
+      if (ctx.abortSignal.aborted) throw new Error(`Agent "${ctx.agentName}" aborted`);
+
+      const skill = skills.find((s) => s.meta.name === planStep.skill);
+      if (!skill) {
+        ctx.logger.warn(`[plan-and-execute] Skill "${planStep.skill}" not found — skipping`);
+        continue;
+      }
+
+      // Derive input from previous results
+      const stepInput = this.resolveStepInput(planStep, input, results);
+
+      ctx.logger.debug(
+        `[plan-and-execute] Executing step "${planStep.step_name}" with skill "${planStep.skill}"`,
+      );
+
+      const t0 = Date.now();
+      const output = await skill.execute(
+        stepInput as Parameters<typeof skill.execute>[0],
+        ctx.toSkillContext(),
+      );
+      const durationMs = Date.now() - t0;
+
+      results.set(planStep.step_name, output);
+
+      trace.push({
+        type: 'action',
+        skill: planStep.skill,
+        input: stepInput,
+        output,
+        timestamp: new Date().toISOString(),
+        content: { step: planStep.step_name, durationMs },
+      });
+
+      // Optional re-plan
+      if (this.options.replanAfterEachStep && replanCount < maxReplans) {
+        const newPlan = await this.replan(skills, input, results, plan, ctx);
+        if (JSON.stringify(newPlan.steps) !== JSON.stringify(plan.steps)) {
+          plan = newPlan;
+          replanCount++;
+          trace.push({
+            type: 'replan',
+            content: { plan, replanCount },
+            timestamp: new Date().toISOString(),
+          });
+          ctx.logger.debug(`[plan-and-execute] Replanned (${replanCount}/${maxReplans})`);
+        }
+      }
+    }
+
+    const finalOutput = results.size === 1
+      ? results.values().next().value
+      : Object.fromEntries(results);
+
+    trace.push({ type: 'finish', output: finalOutput, timestamp: new Date().toISOString() });
+
+    return {
+      output: finalOutput,
+      trace,
+      tokensUsed: ctx.totalTokens,
+      durationMs: Date.now() - startMs,
+    };
+  }
+
+  private async createPlan(
+    skills: Skill[],
+    input: unknown,
+    existingResults: Map<string, unknown>,
+    ctx: AgentContext,
+  ): Promise<Plan> {
+    const skillCatalog = skills.map((s) => ({
+      name: s.meta.name,
+      description: s.meta.description,
+      tags: s.meta.tags ?? [],
+    }));
+
+    const completedStr =
+      existingResults.size > 0
+        ? `\nALREADY COMPLETED: ${[...existingResults.keys()].join(', ')}`
+        : '';
+
+    const prompt =
+      this.options.planPromptTemplate ??
+      `You are a planning agent. Create an execution plan to achieve the goal.
+
+ROLE: ${ctx.agentRole}
+
+AVAILABLE SKILLS:
+${JSON.stringify(skillCatalog, null, 2)}
+
+GOAL INPUT:
+${JSON.stringify(input, null, 2).substring(0, 3000)}
+${completedStr}
+
+Rules:
+- Only include skills that are necessary
+- You may use the same skill multiple times with different step_names
+- depends_on must reference step_names defined earlier in the plan
+- Keep input_description concise — it will be used to build the actual input
+
+Respond with ONLY valid JSON:
+{
+  "reasoning": "why this plan",
+  "steps": [
+    {
+      "step_name": "unique-step-id",
+      "skill": "skill-name",
+      "input_description": "what input to pass and where to get it from",
+      "expected_output": "what this produces",
+      "depends_on": ["step-name"]
+    }
+  ]
+}`;
+
+    const response = await ctx.llm.chat(
+      [{ role: 'user', content: prompt }],
+      { temperature: 0.1, responseFormat: 'json' },
+    );
+    ctx.addTokens(response.usage.totalTokens);
+
+    try {
+      return JSON.parse(response.content) as Plan;
+    } catch {
+      const match = response.content.match(/\{[\s\S]*\}/);
+      if (!match) throw new Error(`Plan-and-execute failed to produce valid JSON plan`);
+      return JSON.parse(match[0]) as Plan;
+    }
+  }
+
+  private async replan(
+    skills: Skill[],
+    input: unknown,
+    results: Map<string, unknown>,
+    currentPlan: Plan,
+    ctx: AgentContext,
+  ): Promise<Plan> {
+    const completedStr = [...results.entries()]
+      .map(([k, v]) => `${k}: ${JSON.stringify(v).substring(0, 200)}`)
+      .join('\n');
+
+    const prompt = `You are re-planning based on actual results.
+
+ROLE: ${ctx.agentRole}
+
+ORIGINAL GOAL: ${JSON.stringify(input).substring(0, 1000)}
+
+ORIGINAL PLAN:
+${JSON.stringify(currentPlan.steps.map((s) => s.step_name), null, 2)}
+
+COMPLETED STEPS AND OUTPUTS:
+${completedStr}
+
+AVAILABLE SKILLS:
+${skills.map((s) => `${s.meta.name}: ${s.meta.description}`).join('\n')}
+
+Do you need to adjust the remaining plan? Produce a complete updated plan (include completed steps too).
+Respond with ONLY valid JSON using the same format as the original plan.`;
+
+    const response = await ctx.llm.chat(
+      [{ role: 'user', content: prompt }],
+      { temperature: 0.1, responseFormat: 'json' },
+    );
+    ctx.addTokens(response.usage.totalTokens);
+
+    try {
+      return JSON.parse(response.content) as Plan;
+    } catch {
+      return currentPlan; // keep original on parse failure
+    }
+  }
+
+  private topologicalSort(steps: PlanStep[]): PlanStep[] {
+    const nameToStep = new Map(steps.map((s) => [s.step_name, s]));
+    const sorted: PlanStep[] = [];
+    const visited = new Set<string>();
+
+    const visit = (name: string): void => {
+      if (visited.has(name)) return;
+      const step = nameToStep.get(name);
+      if (!step) return;
+      for (const dep of step.depends_on) {
+        visit(dep);
+      }
+      visited.add(name);
+      sorted.push(step);
+    };
+
+    for (const step of steps) visit(step.step_name);
+    return sorted;
+  }
+
+  private resolveStepInput(
+    step: PlanStep,
+    originalInput: unknown,
+    results: Map<string, unknown>,
+  ): unknown {
+    // If there are dependencies, merge their outputs
+    if (step.depends_on.length === 0) return originalInput;
+    if (step.depends_on.length === 1) {
+      return results.get(step.depends_on[0]!) ?? originalInput;
+    }
+    // Multiple dependencies: merge all into one object
+    const merged: Record<string, unknown> = { _original: originalInput };
+    for (const dep of step.depends_on) {
+      merged[dep] = results.get(dep);
+    }
+    return merged;
+  }
+}

package/src/strategies/react.ts

@@ -0,0 +1,239 @@
+/**
+ * ReAct strategy — iterative Reasoning + Acting loop.
+ *
+ * Each iteration:
+ *   1. THINK — LLM reasons about what to do next
+ *   2. ACT   — execute the chosen skill
+ *   3. OBSERVE — feed output back to LLM
+ *   4. Repeat until LLM decides to FINISH
+ */
+
+import type { Skill } from '../skill.js';
+import type {
+  Strategy,
+  AgentContext,
+  AgentResult,
+  AgentTraceEntry,
+} from './types.js';
+import { AgentMaxIterationsError } from '../errors.js';
+
+interface ThoughtAction {
+  thought: string;
+  action:
+    | { type: 'use_skill'; skill: string; input: unknown }
+    | { type: 'finish'; output: unknown };
+}
+
+export interface ReActOptions {
+  /** Maximum reasoning iterations before hard stop (default: 10). */
+  maxIterations?: number;
+  /** Reflect and self-correct every N steps (0 = disabled, default: 0). */
+  reflectionInterval?: number;
+  /** Custom system prompt additions. */
+  systemPromptSuffix?: string;
+}
+
+export class ReActStrategy implements Strategy {
+  constructor(private options: ReActOptions = {}) {}
+
+  async execute(
+    skills: Skill[],
+    input: unknown,
+    ctx: AgentContext,
+  ): Promise<AgentResult> {
+    const trace: AgentTraceEntry[] = [];
+    const startMs = Date.now();
+    const maxIter = this.options.maxIterations ?? 10;
+    const reflectionInterval = this.options.reflectionInterval ?? 0;
+
+    const history: Array<{ thought: string; action: unknown; observation: unknown }> = [];
+    const skillMap = new Map(skills.map((s) => [s.meta.name, s]));
+
+    for (let i = 0; i < maxIter; i++) {
+      if (ctx.abortSignal.aborted) throw new Error(`Agent "${ctx.agentName}" aborted`);
+
+      // ── Periodic reflection ────────────────────────────────────────────
+      if (reflectionInterval > 0 && i > 0 && i % reflectionInterval === 0) {
+        const reflection = await this.reflect(history, ctx);
+        trace.push({
+          type: 'reflection',
+          content: reflection,
+          iteration: i,
+          timestamp: new Date().toISOString(),
+        });
+        ctx.logger.debug(`[react] Reflection at step ${i}: ${reflection.substring(0, 100)}`);
+      }
+
+      // ── Think ─────────────────────────────────────────────────────────
+      const thought = await this.think(skills, input, history, ctx, i);
+
+      trace.push({
+        type: 'thought',
+        iteration: i,
+        content: thought.thought,
+        timestamp: new Date().toISOString(),
+      });
+
+      ctx.logger.debug(`[react:${i}] Thought: ${thought.thought.substring(0, 100)}`);
+
+      // ── Check for finish ──────────────────────────────────────────────
+      if (thought.action.type === 'finish') {
+        trace.push({
+          type: 'finish',
+          output: thought.action.output,
+          iteration: i,
+          timestamp: new Date().toISOString(),
+        });
+        return {
+          output: thought.action.output,
+          trace,
+          tokensUsed: ctx.totalTokens,
+          durationMs: Date.now() - startMs,
+        };
+      }
+
+      // ── Act ───────────────────────────────────────────────────────────
+      const skillName = thought.action.skill;
+      const skill = skillMap.get(skillName);
+
+      let observation: unknown;
+
+      if (!skill) {
+        observation = {
+          error: `Skill "${skillName}" not found. Available: ${[...skillMap.keys()].join(', ')}`,
+        };
+        ctx.logger.warn(`[react:${i}] Unknown skill "${skillName}"`);
+      } else {
+        try {
+          ctx.logger.debug(`[react:${i}] Calling skill "${skillName}"`);
+          observation = await skill.execute(
+            thought.action.input as Parameters<typeof skill.execute>[0],
+            ctx.toSkillContext(),
+          );
+          trace.push({
+            type: 'action',
+            skill: skillName,
+            input: thought.action.input,
+            output: observation,
+            iteration: i,
+            timestamp: new Date().toISOString(),
+          });
+        } catch (err) {
+          observation = {
+            error: err instanceof Error ? err.message : String(err),
+          };
+          ctx.logger.warn(`[react:${i}] Skill "${skillName}" error: ${observation}`);
+        }
+      }
+
+      trace.push({
+        type: 'observation',
+        content: observation,
+        iteration: i,
+        timestamp: new Date().toISOString(),
+      });
+
+      history.push({
+        thought: thought.thought,
+        action: thought.action,
+        observation,
+      });
+    }
+
+    throw new AgentMaxIterationsError(ctx.agentName, maxIter);
+  }
+
+  private async think(
+    skills: Skill[],
+    originalInput: unknown,
+    history: Array<{ thought: string; action: unknown; observation: unknown }>,
+    ctx: AgentContext,
+    iteration: number,
+  ): Promise<ThoughtAction> {
+    const skillList = skills
+      .map((s) => `- ${s.meta.name}: ${s.meta.description}`)
+      .join('\n');
+
+    const historyText =
+      history.length === 0
+        ? 'No previous steps.'
+        : history
+            .map(
+              (h, i) =>
+                `[Step ${i + 1}]\nThought: ${h.thought}\nAction: ${JSON.stringify(h.action)}\nObservation: ${JSON.stringify(h.observation).substring(0, 800)}`,
+            )
+            .join('\n\n');
+
+    const systemPrompt = `${ctx.agentRole}
+${this.options.systemPromptSuffix ?? ''}
+
+You operate in a Thought → Action → Observation loop.
+After each action you will see the result (observation) and decide what to do next.
+When you have enough information, use { "type": "finish", "output": {...} } to stop.`;
+
+    const userPrompt = `AVAILABLE SKILLS:
+${skillList}
+
+ORIGINAL INPUT:
+${JSON.stringify(originalInput, null, 2).substring(0, 2000)}
+
+HISTORY (${history.length} steps so far):
+${historyText}
+
+Step ${iteration + 1}: What do you do next?
+
+Respond with ONLY valid JSON:
+{
+  "thought": "your step-by-step reasoning",
+  "action": { "type": "use_skill", "skill": "skill-name", "input": {...} }
+}
+
+OR to finish:
+{
+  "thought": "why I'm done",
+  "action": { "type": "finish", "output": {...} }
+}`;
+
+    const response = await ctx.llm.chat(
+      [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: userPrompt },
+      ],
+      { temperature: 0.2 },
+    );
+    ctx.addTokens(response.usage.totalTokens);
+
+    try {
+      return JSON.parse(response.content) as ThoughtAction;
+    } catch {
+      const match = response.content.match(/\{[\s\S]*\}/);
+      if (!match) {
+        throw new Error(
+          `ReAct: LLM did not produce valid JSON at step ${iteration}. Got: ${response.content.substring(0, 300)}`,
+        );
+      }
+      return JSON.parse(match[0]) as ThoughtAction;
+    }
+  }
+
+  private async reflect(
+    history: Array<{ thought: string; action: unknown; observation: unknown }>,
+    ctx: AgentContext,
+  ): Promise<string> {
+    const summary = history
+      .map((h, i) => `Step ${i + 1}: ${h.thought.substring(0, 80)} → ${JSON.stringify(h.action).substring(0, 80)}`)
+      .join('\n');
+
+    const response = await ctx.llm.chat(
+      [
+        {
+          role: 'user',
+          content: `Review your progress:\n${summary}\n\nAre you on track? Stuck in a loop? Should you change approach? Be brief.`,
+        },
+      ],
+      { temperature: 0.1 },
+    );
+    ctx.addTokens(response.usage.totalTokens);
+    return response.content;
+  }
+}

package/src/strategies/router.ts

@@ -0,0 +1,101 @@
+/**
+ * Router strategy — LLM picks ONE skill to handle the input.
+ *
+ * Useful for triage/classification: incoming request → route to specialist.
+ */
+
+import type { Skill } from '../skill.js';
+import type { Strategy, AgentContext, AgentResult, AgentTraceEntry } from './types.js';
+
+interface RouterDecision {
+  skill_index: number;
+  reasoning: string;
+}
+
+export class RouterStrategy implements Strategy {
+  async execute(
+    skills: Skill[],
+    input: unknown,
+    ctx: AgentContext,
+  ): Promise<AgentResult> {
+    const trace: AgentTraceEntry[] = [];
+    const startMs = Date.now();
+
+    // Build skill catalog
+    const skillList = skills
+      .map((s, i) => `${i}: ${s.meta.name} — ${s.meta.description}`)
+      .join('\n');
+
+    const routingPrompt = `You are a routing agent. Pick the BEST single skill to handle the input.
+
+ROLE: ${ctx.agentRole}
+
+AVAILABLE SKILLS:
+${skillList}
+
+INPUT:
+${JSON.stringify(input, null, 2).substring(0, 3000)}
+
+Respond with ONLY valid JSON — no markdown, no explanation:
+{ "skill_index": <number 0-${skills.length - 1}>, "reasoning": "<brief explanation>" }`;
+
+    ctx.logger.debug(`[router] Routing to best skill among ${skills.length} options`);
+
+    const response = await ctx.llm.chat(
+      [{ role: 'user', content: routingPrompt }],
+      { temperature: 0.1, responseFormat: 'json' },
+    );
+
+    ctx.addTokens(response.usage.totalTokens);
+
+    let decision: RouterDecision;
+    try {
+      decision = JSON.parse(response.content) as RouterDecision;
+    } catch {
+      // Fallback: find JSON in response
+      const match = response.content.match(/\{[\s\S]*\}/);
+      if (!match) {
+        throw new Error(`Router failed to produce valid JSON. Got: ${response.content.substring(0, 200)}`);
+      }
+      decision = JSON.parse(match[0]) as RouterDecision;
+    }
+
+    const chosenSkill = skills[decision.skill_index];
+    if (!chosenSkill) {
+      throw new Error(
+        `Router chose invalid skill index ${decision.skill_index}. Available: 0-${skills.length - 1}`,
+      );
+    }
+
+    trace.push({
+      type: 'route',
+      content: {
+        chosen: chosenSkill.meta.name,
+        index: decision.skill_index,
+        reasoning: decision.reasoning,
+      },
+      timestamp: new Date().toISOString(),
+    });
+
+    ctx.logger.debug(`[router] Chose "${chosenSkill.meta.name}": ${decision.reasoning}`);
+
+    const output = await chosenSkill.execute(
+      input as Parameters<typeof chosenSkill.execute>[0],
+      ctx.toSkillContext(),
+    );
+
+    trace.push({
+      type: 'finish',
+      skill: chosenSkill.meta.name,
+      output,
+      timestamp: new Date().toISOString(),
+    });
+
+    return {
+      output,
+      trace,
+      tokensUsed: ctx.totalTokens,
+      durationMs: Date.now() - startMs,
+    };
+  }
+}

package/src/strategies/sequential.ts

@@ -0,0 +1,55 @@
+/**
+ * Sequential strategy — runs all skills in order, passing output → input.
+ *
+ * The simplest strategy. No LLM calls at the agent level.
+ * Equivalent to a pipeline but wrapped in an agent for observability.
+ */
+
+import type { Skill } from '../skill.js';
+import type { Strategy, AgentContext, AgentResult, AgentTraceEntry } from './types.js';
+
+export class SequentialStrategy implements Strategy {
+  async execute(
+    skills: Skill[],
+    input: unknown,
+    ctx: AgentContext,
+  ): Promise<AgentResult> {
+    const trace: AgentTraceEntry[] = [];
+    const startMs = Date.now();
+    let current = input;
+
+    for (const skill of skills) {
+      if (ctx.abortSignal.aborted) {
+        throw new Error(`Agent "${ctx.agentName}" aborted`);
+      }
+
+      const skillCtx = ctx.toSkillContext();
+      ctx.logger.debug(`[sequential] Running skill "${skill.meta.name}"`);
+      const t0 = Date.now();
+
+      const output = await skill.execute(current as Parameters<typeof skill.execute>[0], skillCtx);
+
+      trace.push({
+        type: 'action',
+        skill: skill.meta.name,
+        input: current,
+        output,
+        timestamp: new Date().toISOString(),
+      });
+
+      ctx.logger.debug(
+        `[sequential] Skill "${skill.meta.name}" done in ${Date.now() - t0}ms`,
+      );
+      current = output;
+    }
+
+    trace.push({ type: 'finish', output: current, timestamp: new Date().toISOString() });
+
+    return {
+      output: current,
+      trace,
+      tokensUsed: ctx.totalTokens,
+      durationMs: Date.now() - startMs,
+    };
+  }
+}