@db-lyon/flowkit 0.10.0 → 0.11.0

package/dist/task/llm-runner.js

@@ -0,0 +1,213 @@
+/**
+ * The single place every LLM call goes through.
+ *
+ * `runCompletion` wraps a raw provider with the cross-cutting concerns that make
+ * model calls production-safe — and does so once, so both the single-shot
+ * `AgentPromptTask` and the agentic `AgentTask` inherit identical behavior:
+ *
+ *   - timeout + abort  — bound every call; abort the provider's in-flight request
+ *   - retry + backoff  — exponential backoff on transient transport failures
+ *   - structured output — validate against the requested JSON Schema and, on a
+ *                         mismatch, re-prompt the model with the concrete errors
+ *                         (the "repair loop") before giving up
+ *   - output cap       — bound response text so a runaway generation can't blow
+ *                         up memory or downstream logs
+ */
+import { noopLogger } from '../logger.js';
+import { validateJson, formatErrors } from './json-schema.js';
+/** Lift the run-control fields out of a task's options into `LLMRunOptions`. */
+export function pickRunOptions(o) {
+    const out = {};
+    if (o.timeout !== undefined)
+        out.timeout = o.timeout;
+    if (o.retries !== undefined)
+        out.retries = o.retries;
+    if (o.retryDelay !== undefined)
+        out.retryDelay = o.retryDelay;
+    if (o.repairAttempts !== undefined)
+        out.repairAttempts = o.repairAttempts;
+    if (o.maxOutputChars !== undefined)
+        out.maxOutputChars = o.maxOutputChars;
+    return out;
+}
+/** A provider call exceeded its timeout. */
+export class LLMTimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LLMTimeoutError';
+    }
+}
+/** Structured output never satisfied the schema, even after repair attempts. */
+export class StructuredOutputError extends Error {
+    rawText;
+    validationErrors;
+    constructor(message, rawText, validationErrors) {
+        super(message);
+        this.rawText = rawText;
+        this.validationErrors = validationErrors;
+        this.name = 'StructuredOutputError';
+    }
+}
+export async function runCompletion(provider, request, options = {}, logger = noopLogger) {
+    const { timeout = 60_000, retries = 2, retryDelay = 500, retryOn, repairAttempts = 1, maxOutputChars = 0, } = options;
+    // The first call goes out exactly as the caller framed it (a bare `prompt`
+    // stays a `prompt`). Only when a repair turn must be appended do we fall back
+    // to a `messages` conversation, seeded from the original prompt/messages.
+    let currentReq = request;
+    let repairsLeft = request.schema ? repairAttempts : 0;
+    let history = request.messages
+        ? [...request.messages]
+        : request.prompt != null
+            ? [{ role: 'user', content: request.prompt }]
+            : [];
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        const raw = await callWithRetry(provider, currentReq, { timeout, retries, retryDelay, retryOn }, logger);
+        const resp = capOutput(raw, maxOutputChars, logger);
+        if (!request.schema)
+            return resp;
+        const coerced = coerceStructured(resp, request.schema);
+        if (!coerced.errors)
+            return { ...resp, parsed: coerced.parsed };
+        if (repairsLeft <= 0) {
+            throw new StructuredOutputError(`LLM output failed schema validation: ${coerced.errors}`, resp.text, coerced.errors);
+        }
+        repairsLeft--;
+        logger.warn({ errors: coerced.errors, repairsLeft }, 'LLM structured output failed validation; requesting repair');
+        history = [
+            ...history,
+            { role: 'assistant', content: resp.text },
+            { role: 'user', content: repairInstruction(coerced.errors) },
+        ];
+        currentReq = { ...request, prompt: undefined, messages: history };
+    }
+}
+// ---------------------------------------------------------------------------
+// Transport: timeout + retry/backoff
+// ---------------------------------------------------------------------------
+async function callWithRetry(provider, req, cfg, logger) {
+    let lastErr = new Error('LLM call never executed');
+    for (let attempt = 0; attempt <= cfg.retries; attempt++) {
+        try {
+            return await callOnce(provider, req, cfg.timeout);
+        }
+        catch (err) {
+            lastErr = err instanceof Error ? err : new Error(String(err));
+            const canRetry = attempt < cfg.retries && (cfg.retryOn ? cfg.retryOn(lastErr) : true);
+            if (!canRetry)
+                break;
+            const delay = cfg.retryDelay * 2 ** attempt;
+            logger.warn({ attempt: attempt + 1, nextDelayMs: delay, error: lastErr.message }, 'LLM call failed; retrying');
+            await sleep(delay);
+        }
+    }
+    throw lastErr;
+}
+async function callOnce(provider, req, timeout) {
+    if (!timeout || timeout <= 0)
+        return provider.complete(req);
+    const controller = new AbortController();
+    const signal = req.signal ? anySignal([req.signal, controller.signal]) : controller.signal;
+    let timer;
+    const timeoutPromise = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            reject(new LLMTimeoutError(`LLM call timed out after ${timeout}ms`));
+        }, timeout);
+    });
+    try {
+        return await Promise.race([provider.complete({ ...req, signal }), timeoutPromise]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/** Combine abort signals — aborts when any input aborts. (Node-version safe.) */
+function anySignal(signals) {
+    const controller = new AbortController();
+    const onAbort = () => {
+        controller.abort();
+        for (const s of signals)
+            s.removeEventListener('abort', onAbort);
+    };
+    for (const s of signals) {
+        if (s.aborted) {
+            controller.abort();
+            break;
+        }
+        s.addEventListener('abort', onAbort, { once: true });
+    }
+    return controller.signal;
+}
+// ---------------------------------------------------------------------------
+// Structured output
+// ---------------------------------------------------------------------------
+/**
+ * Coerce a response into a schema-conforming value: prefer the provider's
+ * `parsed`, else parse JSON out of the text. Returns `{ parsed }` when valid or
+ * `{ errors }` describing the mismatch. Exported so callers (e.g. the agent
+ * loop) can check conformance without forcing an extra model call.
+ */
+export function coerceStructured(resp, schema) {
+    let candidate = resp.parsed;
+    if (candidate === undefined) {
+        const parsed = extractJson(resp.text);
+        if (!parsed.ok)
+            return { errors: `output is not valid JSON (${parsed.error})` };
+        candidate = parsed.value;
+    }
+    const result = validateJson(candidate, schema);
+    if (!result.valid)
+        return { errors: formatErrors(result.errors) };
+    return { parsed: candidate };
+}
+/** Parse JSON from model output, tolerating code fences and surrounding prose. */
+function extractJson(text) {
+    const tryParse = (s) => {
+        try {
+            return { ok: true, value: JSON.parse(s) };
+        }
+        catch {
+            return null;
+        }
+    };
+    const trimmed = text.trim();
+    const direct = tryParse(trimmed);
+    if (direct)
+        return direct;
+    // Strip a ```json … ``` (or plain ```) fence if present.
+    const fence = trimmed.match(/```(?:json)?\s*([\s\S]*?)\s*```/i);
+    if (fence?.[1]) {
+        const fenced = tryParse(fence[1].trim());
+        if (fenced)
+            return fenced;
+    }
+    // Last resort: slice from the first opening bracket to the last closing one.
+    const start = trimmed.search(/[[{]/);
+    const end = Math.max(trimmed.lastIndexOf('}'), trimmed.lastIndexOf(']'));
+    if (start !== -1 && end > start) {
+        const sliced = tryParse(trimmed.slice(start, end + 1));
+        if (sliced)
+            return sliced;
+    }
+    return { ok: false, error: 'no parseable JSON found' };
+}
+function repairInstruction(errors) {
+    return (`Your previous response did not satisfy the required JSON schema. ` +
+        `Validation errors: ${errors}. ` +
+        `Respond again with ONLY valid JSON that satisfies the schema — no prose, no markdown fences.`);
+}
+// ---------------------------------------------------------------------------
+// Output cap
+// ---------------------------------------------------------------------------
+function capOutput(resp, maxChars, logger) {
+    if (!maxChars || maxChars <= 0 || resp.text.length <= maxChars)
+        return resp;
+    logger.warn({ length: resp.text.length, maxChars }, 'LLM output exceeded maxOutputChars; truncating');
+    return { ...resp, text: resp.text.slice(0, maxChars), truncated: true };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=llm-runner.js.map

package/dist/task/llm-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-runner.js","sourceRoot":"","sources":["../../src/task/llm-runner.ts"],"names":[],"mappings":"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"}

package/dist/task/redact.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Logging hygiene for the LLM tasks.
+ *
+ * Provider config and prompts routinely carry API keys, tokens, and large or
+ * sensitive payloads. These helpers keep secrets out of logs and keep log lines
+ * bounded, so attaching a real logger to an agent task is safe by default.
+ */
+/**
+ * Deep-clone `value`, masking the values of any keys that look secret. Strings
+ * longer than `maxString` are truncated with a length marker. Cycles are
+ * collapsed to `[circular]`. Never throws.
+ */
+export declare function redact(value: unknown, maxString?: number, seen?: WeakSet<object>): unknown;
+/** Truncate a string to `max` chars, appending a `(+N more)` marker. */
+export declare function truncate(str: string, max?: number): string;
+/**
+ * A short, log-safe preview of model-bound text: collapses whitespace and
+ * truncates. Use for prompts/outputs you want visible at info level without
+ * dumping the whole payload.
+ */
+export declare function preview(str: string, max?: number): string;
+//# sourceMappingURL=redact.d.ts.map

package/dist/task/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../src/task/redact.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,SAAM,EAAE,IAAI,kBAAwB,GAAG,OAAO,CAgB7F;AAED,wEAAwE;AACxE,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,SAAM,GAAG,MAAM,CAGvD;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,SAAM,GAAG,MAAM,CAGtD"}

package/dist/task/redact.js

@@ -0,0 +1,47 @@
+/**
+ * Logging hygiene for the LLM tasks.
+ *
+ * Provider config and prompts routinely carry API keys, tokens, and large or
+ * sensitive payloads. These helpers keep secrets out of logs and keep log lines
+ * bounded, so attaching a real logger to an agent task is safe by default.
+ */
+const SECRET_KEY = /(?:api[-_]?key|secret|token|password|passwd|authorization|auth|bearer|credential|private[-_]?key)/i;
+const REDACTED = '[redacted]';
+/**
+ * Deep-clone `value`, masking the values of any keys that look secret. Strings
+ * longer than `maxString` are truncated with a length marker. Cycles are
+ * collapsed to `[circular]`. Never throws.
+ */
+export function redact(value, maxString = 500, seen = new WeakSet()) {
+    if (typeof value === 'string')
+        return truncate(value, maxString);
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (seen.has(value))
+        return '[circular]';
+    seen.add(value);
+    if (Array.isArray(value)) {
+        return value.map((v) => redact(v, maxString, seen));
+    }
+    const out = {};
+    for (const [key, v] of Object.entries(value)) {
+        out[key] = SECRET_KEY.test(key) ? REDACTED : redact(v, maxString, seen);
+    }
+    return out;
+}
+/** Truncate a string to `max` chars, appending a `(+N more)` marker. */
+export function truncate(str, max = 500) {
+    if (str.length <= max)
+        return str;
+    return `${str.slice(0, max)}… (+${str.length - max} more chars)`;
+}
+/**
+ * A short, log-safe preview of model-bound text: collapses whitespace and
+ * truncates. Use for prompts/outputs you want visible at info level without
+ * dumping the whole payload.
+ */
+export function preview(str, max = 200) {
+    const collapsed = str.replace(/\s+/g, ' ').trim();
+    return truncate(collapsed, max);
+}
+//# sourceMappingURL=redact.js.map

package/dist/task/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../../src/task/redact.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,UAAU,GAAG,oGAAoG,CAAC;AAExH,MAAM,QAAQ,GAAG,YAAY,CAAC;AAE9B;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAC,KAAc,EAAE,SAAS,GAAG,GAAG,EAAE,OAAO,IAAI,OAAO,EAAU;IAClF,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IACjE,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAE9D,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,YAAY,CAAC;IACzC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAEhB,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC;IACtD,CAAC;IAED,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;QACxE,GAAG,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,QAAQ,CAAC,GAAW,EAAE,GAAG,GAAG,GAAG;IAC7C,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,GAAG,CAAC;IAClC,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,OAAO,GAAG,CAAC,MAAM,GAAG,GAAG,cAAc,CAAC;AACnE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,GAAW,EAAE,GAAG,GAAG,GAAG;IAC5C,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAClD,OAAO,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;AAClC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@db-lyon/flowkit",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "YAML-configured task and flow orchestration engine",
   "type": "module",
   "main": "dist/index.js",