@flomatai/core 0.1.0

package/src/skills/io-skill.ts

@@ -0,0 +1,133 @@
+/**
+ * IOSkill — a skill that performs file, HTTP, or other IO operations.
+ *
+ * Thin wrapper around TransformSkill but with 'io' tag and
+ * helper factories for common patterns.
+ */
+
+import { z, type ZodSchema } from 'zod';
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { dirname } from 'path';
+import type { Skill, SkillContext } from '../skill.js';
+import { createTransformSkill } from './transform-skill.js';
+
+// ── HTTP GET ─────────────────────────────────────────────────────────────────
+
+export function createHttpGetSkill(options: {
+  name: string;
+  description?: string;
+  /** URL factory from input. */
+  url: (input: Record<string, unknown>) => string;
+  /** Headers factory from input. */
+  headers?: (input: Record<string, unknown>) => Record<string, string>;
+  /** Parse the response. Default: parse as JSON. */
+  parseResponse?: (body: string, status: number) => unknown;
+  timeout?: number;
+  retries?: number;
+}): Skill {
+  return createTransformSkill({
+    name: options.name,
+    description: options.description ?? `HTTP GET skill: ${options.name}`,
+    tags: ['io', 'http'],
+    inputSchema: z.record(z.unknown()),
+    outputSchema: z.unknown() as ZodSchema<unknown>,
+    timeout: options.timeout,
+    async transform(input) {
+      const url = options.url(input);
+      const headers = options.headers?.(input) ?? {};
+      const res = await fetch(url, { headers });
+      const body = await res.text();
+      if (options.parseResponse) {
+        return options.parseResponse(body, res.status);
+      }
+      try { return JSON.parse(body); } catch { return body; }
+    },
+  });
+}
+
+// ── HTTP POST ────────────────────────────────────────────────────────────────
+
+export function createHttpPostSkill(options: {
+  name: string;
+  description?: string;
+  url: (input: Record<string, unknown>) => string;
+  body: (input: Record<string, unknown>) => unknown;
+  headers?: (input: Record<string, unknown>) => Record<string, string>;
+  parseResponse?: (body: string, status: number) => unknown;
+  timeout?: number;
+}): Skill {
+  return createTransformSkill({
+    name: options.name,
+    description: options.description ?? `HTTP POST skill: ${options.name}`,
+    tags: ['io', 'http'],
+    inputSchema: z.record(z.unknown()),
+    outputSchema: z.unknown() as ZodSchema<unknown>,
+    timeout: options.timeout,
+    async transform(input) {
+      const url = options.url(input);
+      const headers = { 'Content-Type': 'application/json', ...(options.headers?.(input) ?? {}) };
+      const body = JSON.stringify(options.body(input));
+      const res = await fetch(url, { method: 'POST', headers, body });
+      const text = await res.text();
+      if (options.parseResponse) {
+        return options.parseResponse(text, res.status);
+      }
+      try { return JSON.parse(text); } catch { return text; }
+    },
+  });
+}
+
+// ── File Read ─────────────────────────────────────────────────────────────────
+
+export function createReadFileSkill(options: {
+  name: string;
+  description?: string;
+  path: (input: Record<string, unknown>) => string;
+  encoding?: BufferEncoding;
+}): Skill {
+  return createTransformSkill({
+    name: options.name,
+    description: options.description ?? `Read file skill: ${options.name}`,
+    tags: ['io', 'file'],
+    inputSchema: z.record(z.unknown()),
+    outputSchema: z.object({ content: z.string(), path: z.string() }),
+    async transform(input) {
+      const path = options.path(input);
+      const content = await readFile(path, options.encoding ?? 'utf-8');
+      return { content, path };
+    },
+  });
+}
+
+// ── File Write ────────────────────────────────────────────────────────────────
+
+export function createWriteFileSkill(options: {
+  name: string;
+  description?: string;
+  path: (input: Record<string, unknown>) => string;
+  content: (input: Record<string, unknown>) => string;
+  encoding?: BufferEncoding;
+}): Skill {
+  return createTransformSkill({
+    name: options.name,
+    description: options.description ?? `Write file skill: ${options.name}`,
+    tags: ['io', 'file'],
+    inputSchema: z.record(z.unknown()),
+    outputSchema: z.object({ path: z.string(), bytesWritten: z.number() }),
+    async transform(input) {
+      const path = options.path(input);
+      const content = options.content(input);
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, content, options.encoding ?? 'utf-8');
+      return { path, bytesWritten: Buffer.byteLength(content) };
+    },
+  });
+}
+
+/** Namespace export */
+export const IOSkill = {
+  httpGet: createHttpGetSkill,
+  httpPost: createHttpPostSkill,
+  readFile: createReadFileSkill,
+  writeFile: createWriteFileSkill,
+};

package/src/skills/llm-skill.ts

@@ -0,0 +1,207 @@
+/**
+ * LLMSkill — builds a Skill that calls an LLM with a prompt template.
+ *
+ * The primary skill type for LLM-backed operations.
+ */
+
+import { z, type ZodSchema } from 'zod';
+import type { Skill, SkillMeta, SkillContext } from '../skill.js';
+import type { Message } from '../types.js';
+import { SkillError, SkillValidationError } from '../errors.js';
+import { withRetry, withTimeout } from '../llm-provider.js';
+
+// ── LLMSkill Config ───────────────────────────────────────────────────────────
+
+export interface LLMSkillConfig<TInput, TOutput> {
+  /** Unique skill name. */
+  name: string;
+  /** Human-readable description used in agent routing/planning prompts. */
+  description: string;
+  /** Version string (default '1.0.0'). */
+  version?: string;
+  /** Tags for categorization. */
+  tags?: string[];
+  /**
+   * Which LLM from the Orchestrator registry to use.
+   * Defaults to 'default'. Can be overridden per-execution.
+   */
+  llm?: string;
+  /**
+   * Prompt factory. Receives validated input, returns prompt string or messages array.
+   */
+  prompt: (input: TInput) => string | Message[];
+  /**
+   * Optional system message prepended to every call.
+   */
+  systemMessage?: string | ((input: TInput) => string);
+  /**
+   * Zod schema for input validation.
+   */
+  inputSchema: ZodSchema<TInput>;
+  /**
+   * Zod schema for output validation.
+   */
+  outputSchema: ZodSchema<TOutput>;
+  /**
+   * Function to parse the raw LLM text response into TOutput.
+   * If not provided, the raw text is returned as-is (must match outputSchema).
+   */
+  parseOutput?: (raw: string, input: TInput) => TOutput;
+  /**
+   * LLM call options (temperature, maxTokens, etc.).
+   */
+  llmOptions?: {
+    temperature?: number;
+    maxTokens?: number;
+    responseFormat?: 'text' | 'json';
+  };
+  /** Number of retries on LLM failure (default 1). */
+  retries?: number;
+  /** Timeout in ms (default none). */
+  timeout?: number;
+  /** Cache config. */
+  cache?: SkillMeta['cache'];
+}
+
+// ── LLMSkill Builder ──────────────────────────────────────────────────────────
+
+export function createLLMSkill<TInput, TOutput>(
+  config: LLMSkillConfig<TInput, TOutput>,
+): Skill<TInput, TOutput> {
+  const meta: SkillMeta = {
+    name: config.name,
+    description: config.description,
+    version: config.version ?? '1.0.0',
+    tags: config.tags ?? ['llm'],
+    retries: config.retries ?? 1,
+    timeout: config.timeout,
+    cache: config.cache,
+  };
+
+  return {
+    meta,
+    inputSchema: config.inputSchema,
+    outputSchema: config.outputSchema,
+
+    async execute(input: TInput, ctx: SkillContext): Promise<TOutput> {
+      // ── Input validation ──
+      const parsed = config.inputSchema.safeParse(input);
+      if (!parsed.success) {
+        throw new SkillValidationError(
+          config.name,
+          'input',
+          `Input validation failed: ${parsed.error.message}`,
+          parsed.error.issues,
+        );
+      }
+      const validInput = parsed.data;
+
+      // ── Cache lookup ──
+      if (config.cache) {
+        const cacheKey = `llmskill:${config.name}:${config.cache.key(validInput)}`;
+        const cached = await ctx.state.get<TOutput>(cacheKey);
+        if (cached !== null) {
+          ctx.logger.debug(`Cache hit for skill "${config.name}"`);
+          return cached;
+        }
+      }
+
+      // ── Resolve LLM ──
+      const llm = ctx.getLLM(config.llm ?? 'default');
+
+      // ── Build messages ──
+      const promptResult = config.prompt(validInput);
+      let messages: Message[];
+
+      if (typeof promptResult === 'string') {
+        messages = [{ role: 'user', content: promptResult }];
+      } else {
+        messages = promptResult;
+      }
+
+      // Prepend system message if provided
+      if (config.systemMessage) {
+        const sysContent =
+          typeof config.systemMessage === 'string'
+            ? config.systemMessage
+            : config.systemMessage(validInput);
+        messages = [{ role: 'system', content: sysContent }, ...messages];
+      }
+
+      // ── Execute with retry/timeout ──
+      const retries = config.retries ?? 1;
+      const timeout = config.timeout;
+
+      const doCall = () =>
+        llm.chat(messages, {
+          temperature: config.llmOptions?.temperature,
+          maxTokens: config.llmOptions?.maxTokens,
+          responseFormat: config.llmOptions?.responseFormat,
+          retries: 0, // retries handled here
+        });
+
+      const callWithRetry = () =>
+        withRetry(
+          doCall,
+          retries,
+          (attempt, err) =>
+            ctx.logger.warn(
+              `Skill "${config.name}" retry ${attempt}/${retries}: ${err.message}`,
+            ),
+        );
+
+      const response = await (timeout
+        ? withTimeout(callWithRetry, timeout, config.name)
+        : callWithRetry());
+
+      ctx.emit('llm:response', {
+        skill: config.name,
+        tokens: response.usage.totalTokens,
+        model: response.model,
+      });
+
+      // ── Parse output ──
+      let output: TOutput;
+      try {
+        if (config.parseOutput) {
+          output = config.parseOutput(response.content, validInput);
+        } else {
+          // Try JSON parse if schema expects object, else return raw string
+          try {
+            output = JSON.parse(response.content) as TOutput;
+          } catch {
+            output = response.content as unknown as TOutput;
+          }
+        }
+      } catch (err) {
+        throw new SkillError(
+          config.name,
+          `Output parsing failed: ${err instanceof Error ? err.message : String(err)}`,
+          { raw: response.content.substring(0, 500) },
+        );
+      }
+
+      // ── Output validation ──
+      const outParsed = config.outputSchema.safeParse(output);
+      if (!outParsed.success) {
+        ctx.logger.warn(
+          `Skill "${config.name}" output failed schema validation — returning raw`,
+          outParsed.error.issues,
+        );
+        // Don't hard-fail on output validation — return what we have
+        // This matches real-world LLM usage where output schema is a guide not a gate
+      }
+
+      // ── Cache store ──
+      if (config.cache) {
+        const cacheKey = `llmskill:${config.name}:${config.cache.key(validInput)}`;
+        await ctx.state.set(cacheKey, output, config.cache.ttl);
+      }
+
+      return output;
+    },
+  };
+}
+
+/** Namespace export for ergonomic usage: LLMSkill.create(...) */
+export const LLMSkill = { create: createLLMSkill };

package/src/skills/transform-skill.ts

@@ -0,0 +1,61 @@
+/**
+ * TransformSkill — a pure data transformation skill (no LLM).
+ *
+ * Pure data transformation skill.
+ */
+
+import type { ZodSchema } from 'zod';
+import type { Skill, SkillMeta, SkillContext } from '../skill.js';
+import { SkillValidationError } from '../errors.js';
+
+export interface TransformSkillConfig<TInput, TOutput> {
+  name: string;
+  description: string;
+  version?: string;
+  tags?: string[];
+  inputSchema: ZodSchema<TInput>;
+  outputSchema: ZodSchema<TOutput>;
+  /**
+   * The transformation function. Pure sync or async.
+   * The second argument (ctx) is optional — most transforms won't need it.
+   */
+  transform: (input: TInput, ctx?: SkillContext) => TOutput | Promise<TOutput>;
+  timeout?: number;
+}
+
+export function createTransformSkill<TInput, TOutput>(
+  config: TransformSkillConfig<TInput, TOutput>,
+): Skill<TInput, TOutput> {
+  const meta: SkillMeta = {
+    name: config.name,
+    description: config.description,
+    version: config.version ?? '1.0.0',
+    tags: config.tags ?? ['transform'],
+    timeout: config.timeout,
+  };
+
+  return {
+    meta,
+    inputSchema: config.inputSchema,
+    outputSchema: config.outputSchema,
+
+    async execute(input: TInput, ctx: SkillContext): Promise<TOutput> {
+      // Input validation
+      const parsed = config.inputSchema.safeParse(input);
+      if (!parsed.success) {
+        throw new SkillValidationError(
+          config.name,
+          'input',
+          `Input validation failed: ${parsed.error.message}`,
+          parsed.error.issues,
+        );
+      }
+
+      const output = await config.transform(parsed.data, ctx);
+      return output;
+    },
+  };
+}
+
+/** Namespace export: TransformSkill.create(...) */
+export const TransformSkill = { create: createTransformSkill };

package/src/state/file-store.ts

@@ -0,0 +1,119 @@
+/**
+ * File-based StateStore — persists data as JSON files.
+ * Good for development and small-scale use. No external dependencies.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync } from 'fs';
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { join, dirname } from 'path';
+import type { StateStore, RunFilter } from './types.js';
+import type { PipelineRun } from '../types.js';
+
+interface CacheEntry {
+  value: unknown;
+  expiresAt: number | null;
+}
+
+interface FileStoreData {
+  cache: Record<string, CacheEntry>;
+  runs: Record<string, PipelineRun>;
+  checkpoints: Record<string, unknown>;
+}
+
+export class FileStore implements StateStore {
+  private readonly dataFile: string;
+  private data: FileStoreData = { cache: {}, runs: {}, checkpoints: {} };
+
+  constructor(dataDir = '.flomatai') {
+    this.dataFile = join(dataDir, 'store.json');
+  }
+
+  async init(): Promise<void> {
+    await mkdir(dirname(this.dataFile), { recursive: true });
+    if (existsSync(this.dataFile)) {
+      try {
+        const raw = await readFile(this.dataFile, 'utf-8');
+        this.data = JSON.parse(raw) as FileStoreData;
+      } catch {
+        this.data = { cache: {}, runs: {}, checkpoints: {} };
+      }
+    }
+  }
+
+  async close(): Promise<void> {
+    await this.flush();
+  }
+
+  private async flush(): Promise<void> {
+    await mkdir(dirname(this.dataFile), { recursive: true });
+    await writeFile(this.dataFile, JSON.stringify(this.data, null, 2), 'utf-8');
+  }
+
+  async get<T>(key: string): Promise<T | null> {
+    const entry = this.data.cache[key];
+    if (!entry) return null;
+    if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+      delete this.data.cache[key];
+      return null;
+    }
+    return entry.value as T;
+  }
+
+  async set<T>(key: string, value: T, ttlSeconds?: number): Promise<void> {
+    this.data.cache[key] = {
+      value,
+      expiresAt: ttlSeconds ? Date.now() + ttlSeconds * 1000 : null,
+    };
+    await this.flush();
+  }
+
+  async delete(key: string): Promise<void> {
+    delete this.data.cache[key];
+    await this.flush();
+  }
+
+  async has(key: string): Promise<boolean> {
+    const v = await this.get(key);
+    return v !== null;
+  }
+
+  async saveRun(run: PipelineRun): Promise<void> {
+    this.data.runs[run.id] = { ...run };
+    await this.flush();
+  }
+
+  async getRun(runId: string): Promise<PipelineRun | null> {
+    return this.data.runs[runId] ?? null;
+  }
+
+  async listRuns(filter?: RunFilter): Promise<PipelineRun[]> {
+    let runs = Object.values(this.data.runs).sort(
+      (a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime(),
+    );
+    if (filter?.pipelineName) {
+      runs = runs.filter((r) => r.pipelineName === filter.pipelineName);
+    }
+    if (filter?.status) {
+      runs = runs.filter((r) => r.status === filter.status);
+    }
+    const offset = filter?.offset ?? 0;
+    const limit = filter?.limit ?? 50;
+    return runs.slice(offset, offset + limit);
+  }
+
+  async saveCheckpoint(runId: string, stepName: string, data: unknown): Promise<void> {
+    this.data.checkpoints[`${runId}::${stepName}`] = data;
+    await this.flush();
+  }
+
+  async getCheckpoint(runId: string, stepName: string): Promise<unknown | null> {
+    return this.data.checkpoints[`${runId}::${stepName}`] ?? null;
+  }
+
+  async clearCheckpoints(runId: string): Promise<void> {
+    for (const key of Object.keys(this.data.checkpoints)) {
+      if (key.startsWith(`${runId}::`)) delete this.data.checkpoints[key];
+    }
+    await this.flush();
+  }
+}

package/src/state/memory-store.ts

@@ -0,0 +1,82 @@
+/**
+ * In-memory StateStore — useful for testing and single-run pipelines.
+ * No persistence; data is lost on process exit.
+ */
+
+import type { StateStore, RunFilter } from './types.js';
+import type { PipelineRun } from '../types.js';
+
+interface CacheEntry {
+  value: unknown;
+  expiresAt: number | null; // null = no expiry
+}
+
+export class MemoryStore implements StateStore {
+  private cache = new Map<string, CacheEntry>();
+  private runs = new Map<string, PipelineRun>();
+  private checkpoints = new Map<string, unknown>(); // key: `${runId}::${stepName}`
+
+  async init(): Promise<void> { /* no-op */ }
+  async close(): Promise<void> { /* no-op */ }
+
+  async get<T>(key: string): Promise<T | null> {
+    const entry = this.cache.get(key);
+    if (!entry) return null;
+    if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return null;
+    }
+    return entry.value as T;
+  }
+
+  async set<T>(key: string, value: T, ttlSeconds?: number): Promise<void> {
+    this.cache.set(key, {
+      value,
+      expiresAt: ttlSeconds ? Date.now() + ttlSeconds * 1000 : null,
+    });
+  }
+
+  async delete(key: string): Promise<void> {
+    this.cache.delete(key);
+  }
+
+  async has(key: string): Promise<boolean> {
+    const v = await this.get(key);
+    return v !== null;
+  }
+
+  async saveRun(run: PipelineRun): Promise<void> {
+    this.runs.set(run.id, { ...run });
+  }
+
+  async getRun(runId: string): Promise<PipelineRun | null> {
+    return this.runs.get(runId) ?? null;
+  }
+
+  async listRuns(filter?: RunFilter): Promise<PipelineRun[]> {
+    let runs = [...this.runs.values()].reverse(); // newest first
+    if (filter?.pipelineName) {
+      runs = runs.filter((r) => r.pipelineName === filter.pipelineName);
+    }
+    if (filter?.status) {
+      runs = runs.filter((r) => r.status === filter.status);
+    }
+    const offset = filter?.offset ?? 0;
+    const limit = filter?.limit ?? 50;
+    return runs.slice(offset, offset + limit);
+  }
+
+  async saveCheckpoint(runId: string, stepName: string, data: unknown): Promise<void> {
+    this.checkpoints.set(`${runId}::${stepName}`, data);
+  }
+
+  async getCheckpoint(runId: string, stepName: string): Promise<unknown | null> {
+    return this.checkpoints.get(`${runId}::${stepName}`) ?? null;
+  }
+
+  async clearCheckpoints(runId: string): Promise<void> {
+    for (const key of this.checkpoints.keys()) {
+      if (key.startsWith(`${runId}::`)) this.checkpoints.delete(key);
+    }
+  }
+}

package/src/state/types.ts

@@ -0,0 +1,53 @@
+/**
+ * StateStore — pluggable persistence interface.
+ *
+ * Adapters: @flomatai/state-file (default), @flomatai/state-sqlite,
+ *           @flomatai/state-redis, @flomatai/state-postgres
+ */
+
+import type { PipelineRun } from '../types.js';
+
+// ── Core Store Interface ──────────────────────────────────────────────────────
+
+export interface StateStore {
+  /** Initialize the store (open connections, create tables, etc.). */
+  init(): Promise<void>;
+  /** Tear down the store (close connections). */
+  close(): Promise<void>;
+
+  // ── Key/Value ────────────────────────────────────────────────────────────
+
+  /** Get a value by key. Returns null if not found or expired. */
+  get<T>(key: string): Promise<T | null>;
+  /** Set a value with optional TTL (seconds). */
+  set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+  /** Delete a key. */
+  delete(key: string): Promise<void>;
+  /** Check if a key exists. */
+  has(key: string): Promise<boolean>;
+
+  // ── Run History ──────────────────────────────────────────────────────────
+
+  /** Persist a pipeline run (upsert by run.id). */
+  saveRun(run: PipelineRun): Promise<void>;
+  /** Retrieve a run by ID. */
+  getRun(runId: string): Promise<PipelineRun | null>;
+  /** List runs, newest first. */
+  listRuns(filter?: RunFilter): Promise<PipelineRun[]>;
+
+  // ── Checkpoints (for resume) ─────────────────────────────────────────────
+
+  /** Save a step checkpoint so a failed run can be resumed. */
+  saveCheckpoint(runId: string, stepName: string, data: unknown): Promise<void>;
+  /** Get a step checkpoint. */
+  getCheckpoint(runId: string, stepName: string): Promise<unknown | null>;
+  /** Clear all checkpoints for a run (after successful completion). */
+  clearCheckpoints(runId: string): Promise<void>;
+}
+
+export interface RunFilter {
+  pipelineName?: string;
+  status?: string;
+  limit?: number;
+  offset?: number;
+}

package/src/strategies/custom.ts

@@ -0,0 +1,24 @@
+/**
+ * Custom strategy — user provides their own strategy function.
+ * Maximum flexibility.
+ */
+
+import type { Skill } from '../skill.js';
+import type {
+  Strategy,
+  AgentContext,
+  AgentResult,
+  CustomStrategyFn,
+} from './types.js';
+
+export class CustomStrategy implements Strategy {
+  constructor(private fn: CustomStrategyFn) {}
+
+  async execute(
+    skills: Skill[],
+    input: unknown,
+    ctx: AgentContext,
+  ): Promise<AgentResult> {
+    return this.fn(skills, input, ctx);
+  }
+}