qlogicagent 0.2.1 → 0.3.0

package/dist/orchestration/parallel-tool-calls.js

@@ -1,59 +0,0 @@
-export function normalizeParallelToolCallsPreference(rawValue) {
-    if (rawValue === undefined) {
-        return undefined;
-    }
-    if (typeof rawValue === "boolean") {
-        return { kind: "enabled", enabled: rawValue };
-    }
-    if (rawValue === null) {
-        return { kind: "suppressed" };
-    }
-    return {
-        kind: "invalid",
-        summary: typeof rawValue === "string" ? rawValue : typeof rawValue,
-    };
-}
-export function resolveParallelToolCallScheduling(params) {
-    const warnings = [];
-    const preference = normalizeParallelToolCallsPreference(params.requestedPreference);
-    const capabilityMap = new Map((params.toolCapabilities ?? []).map((capability) => [capability.name, capability]));
-    let enabled = params.providerSupportsParallel !== false;
-    if (preference?.kind === "enabled") {
-        enabled = preference.enabled && params.providerSupportsParallel !== false;
-    }
-    else if (preference?.kind === "suppressed") {
-        enabled = false;
-    }
-    else if (preference?.kind === "invalid") {
-        warnings.push(`ignoring invalid parallel_tool_calls param: ${preference.summary}`);
-    }
-    if (enabled && params.providerSupportsParallel === false) {
-        warnings.push("provider does not support parallel tool calls; downgraded to serial execution.");
-    }
-    const batches = [];
-    let currentParallelBatch = [];
-    const flushParallelBatch = () => {
-        if (currentParallelBatch.length === 0) {
-            return;
-        }
-        batches.push({ mode: "parallel", calls: currentParallelBatch });
-        currentParallelBatch = [];
-    };
-    for (const toolCall of params.toolCalls) {
-        const capability = capabilityMap.get(toolCall.function.name);
-        const mustSerialize = !enabled || capability?.requiresApproval === true || capability?.serialOnly === true || capability?.parallelSafe === false || capability?.approvalMode === "user-confirm";
-        if (mustSerialize) {
-            flushParallelBatch();
-            batches.push({ mode: "serial", calls: [toolCall] });
-            continue;
-        }
-        currentParallelBatch.push(toolCall);
-    }
-    flushParallelBatch();
-    return {
-        enabled,
-        mode: batches.some((batch) => batch.mode === "parallel" && batch.calls.length > 1) ? "parallel" : "serial",
-        batches,
-        warnings,
-    };
-}

package/dist/orchestration/prompt-cache-strategy.js

@@ -1,228 +0,0 @@
-// ============================================================
-// Prompt cache marking strategy — identify optimal breakpoints
-// in a message array for provider-level prefix caching.
-//
-// Providers like Anthropic cache message prefixes: if consecutive
-// requests share identical leading messages, the cached portion
-// skips re-tokenization and re-processing. The strategy here
-// decides WHERE to place cache breakpoints (up to maxBreakpoints)
-// to maximise prefix reuse across turns.
-// ============================================================
-// ── Defaults ────────────────────────────────────────────────
-export const DEFAULT_PROMPT_CACHE_POLICY = {
-    maxBreakpoints: 4,
-    retention: "short",
-    minSegmentTokens: 256,
-    recentTailCount: 2,
-    markToolDefinitions: true,
-};
-// ── Core strategy ───────────────────────────────────────────
-/**
- * Analyse a message array and return recommended cache breakpoints.
- *
- * The algorithm:
- * 1. Classify each message into segments (system / tool-def / conversation / recent).
- * 2. Identify segment boundaries where the classification changes.
- * 3. Rank boundaries by estimated token cost (heaviest first).
- * 4. Select the top `maxBreakpoints` that meet `minSegmentTokens`.
- *
- * @param messages        The conversation message array (in order).
- * @param estimateTokens  Optional per-message token estimator. Falls back to
- *                        character-length heuristic (1 token ≈ 4 chars).
- * @param policy          Cache marking policy (uses defaults if omitted).
- */
-export function computeCacheBreakpoints(messages, estimateTokens, policy = {}) {
-    const p = { ...DEFAULT_PROMPT_CACHE_POLICY, ...policy };
-    const estimate = estimateTokens ?? defaultTokenEstimator;
-    if (p.retention === "none" || messages.length === 0) {
-        return { breakpoints: [], estimatedCacheableTokens: 0, retention: p.retention };
-    }
-    // Classify every message
-    const recentStart = Math.max(0, messages.length - p.recentTailCount);
-    const classified = messages.map((msg, i) => ({
-        index: i,
-        kind: i >= recentStart ? "recent" : classifyMessage(msg, p),
-        tokens: estimate(msg),
-    }));
-    // Build contiguous segments by kind
-    const segments = [];
-    let current;
-    for (const entry of classified) {
-        if (!current || current.kind !== entry.kind) {
-            if (current)
-                segments.push(current);
-            current = { kind: entry.kind, startIndex: entry.index, endIndex: entry.index, tokens: entry.tokens };
-        }
-        else {
-            current.endIndex = entry.index;
-            current.tokens += entry.tokens;
-        }
-    }
-    if (current)
-        segments.push(current);
-    // Candidate breakpoints: end of each non-recent segment meeting the threshold
-    const candidates = [];
-    for (const seg of segments) {
-        if (seg.kind === "recent")
-            continue;
-        if (seg.tokens < p.minSegmentTokens)
-            continue;
-        candidates.push({
-            index: seg.endIndex,
-            segment: seg.kind,
-            estimatedTokens: seg.tokens,
-        });
-    }
-    // Rank by tokens descending, pick top N
-    candidates.sort((a, b) => (b.estimatedTokens ?? 0) - (a.estimatedTokens ?? 0));
-    const selected = candidates.slice(0, p.maxBreakpoints);
-    // Re-sort by index ascending for stable output
-    selected.sort((a, b) => a.index - b.index);
-    const estimatedCacheableTokens = selected.reduce((sum, bp) => sum + (bp.estimatedTokens ?? 0), 0);
-    return { breakpoints: selected, estimatedCacheableTokens, retention: p.retention };
-}
-/**
- * Apply cache_control markers to a mutable message array based on breakpoints.
- *
- * For each breakpoint index, the last content block of that message gets a
- * `cache_control: { type: "ephemeral" }` annotation (Anthropic format).
- * String content is promoted to a text content block array.
- *
- * This is a pure transform — it returns a new array with shallow-cloned messages.
- */
-export function applyCacheMarkers(messages, breakpoints) {
-    const bpSet = new Set(breakpoints.map((bp) => bp.index));
-    return messages.map((msg, i) => {
-        if (!bpSet.has(i))
-            return msg;
-        return injectCacheControl(msg);
-    });
-}
-/**
- * Estimate the cache savings ratio for a turn.
- *
- * @param totalTokens    Total input tokens for the turn.
- * @param cacheableTokens  Tokens covered by cache breakpoints.
- * @param cacheHitRatio  Fraction of cacheable tokens actually served from cache (0–1).
- * @returns Estimated fraction of input tokens saved (0–1).
- */
-export function estimateCacheSavingsRatio(totalTokens, cacheableTokens, cacheHitRatio = 1) {
-    if (totalTokens <= 0 || cacheableTokens <= 0)
-        return 0;
-    return Math.min(1, (cacheableTokens * Math.max(0, Math.min(1, cacheHitRatio))) / totalTokens);
-}
-// ── Helpers ─────────────────────────────────────────────────
-function classifyMessage(msg, policy) {
-    const role = msg.role;
-    if (role === "system" || role === "developer")
-        return "system";
-    if (policy.markToolDefinitions && role === "tool")
-        return "conversation";
-    // Tool-call results are part of conversation flow
-    if (msg.tool_call_id)
-        return "conversation";
-    return "conversation";
-}
-function defaultTokenEstimator(msg) {
-    const content = msg.content;
-    if (typeof content === "string")
-        return Math.ceil(content.length / 4);
-    if (Array.isArray(content)) {
-        let chars = 0;
-        for (const part of content) {
-            if (typeof part === "string")
-                chars += part.length;
-            else if (part && typeof part === "object" && "text" in part) {
-                chars += typeof part.text === "string"
-                    ? (part.text).length
-                    : 0;
-            }
-        }
-        return Math.ceil(chars / 4);
-    }
-    return 0;
-}
-function injectCacheControl(msg) {
-    const clone = { ...msg };
-    const content = clone.content;
-    if (typeof content === "string") {
-        // Promote string to text content block with cache_control
-        clone.content = [
-            { type: "text", text: content, cache_control: { type: "ephemeral" } },
-        ];
-    }
-    else if (Array.isArray(content) && content.length > 0) {
-        const newContent = content.map((part, idx) => {
-            if (idx !== content.length - 1)
-                return part;
-            if (part && typeof part === "object") {
-                return { ...part, cache_control: { type: "ephemeral" } };
-            }
-            return part;
-        });
-        clone.content = newContent;
-    }
-    return clone;
-}
-// ── CC-aligned Fork Prefix Cache ────────────────────────────
-/**
- * Determine the optimal cache marker position for fork scenarios.
- *
- * CC pattern:
- * - Normal request: marker on messages[length - 1] (last message)
- * - Fork (skipCacheWrite): marker on messages[length - 2] (shared prefix point)
- *
- * This ensures all fork children produce byte-identical API request prefix up to
- * the marker, maximising cache reuse.
- */
-export function resolveForkCacheMarkerIndex(messagesLength, options = {}) {
-    if (messagesLength <= 0)
-        return -1;
-    if (options.skipCacheWrite || options.isForkChild) {
-        // Fork children: marker goes on the shared prefix (second-to-last message)
-        return Math.max(0, messagesLength - 2);
-    }
-    // Normal: marker on last message
-    return messagesLength - 1;
-}
-export function createCacheBreakDetectionState() {
-    return { systemHash: null, toolsHash: null, modelId: null, thinkingEnabled: null };
-}
-/**
- * Detect if a cache break has occurred by comparing current request properties
- * against the last known state.
- *
- * Returns the list of fields that changed (empty = no break).
- */
-export function detectCacheBreaks(state, current) {
-    const events = [];
-    if (state.systemHash !== null && state.systemHash !== current.systemHash) {
-        events.push({ field: "system", previousHash: state.systemHash, currentHash: current.systemHash });
-    }
-    if (state.toolsHash !== null && state.toolsHash !== current.toolsHash) {
-        events.push({ field: "tools", previousHash: state.toolsHash, currentHash: current.toolsHash });
-    }
-    if (state.modelId !== null && state.modelId !== current.modelId) {
-        events.push({ field: "model", previousHash: state.modelId, currentHash: current.modelId });
-    }
-    if (state.thinkingEnabled !== null && state.thinkingEnabled !== current.thinkingEnabled) {
-        events.push({ field: "thinking", previousHash: String(state.thinkingEnabled), currentHash: String(current.thinkingEnabled) });
-    }
-    // Update state
-    state.systemHash = current.systemHash;
-    state.toolsHash = current.toolsHash;
-    state.modelId = current.modelId;
-    state.thinkingEnabled = current.thinkingEnabled;
-    return events;
-}
-/**
- * Compute a lightweight hash for cache break detection.
- * Uses DJB2 algorithm (fast, good distribution for strings).
- */
-export function quickHash(input) {
-    let hash = 5381;
-    for (let i = 0; i < input.length; i++) {
-        hash = ((hash << 5) + hash + input.charCodeAt(i)) | 0;
-    }
-    return (hash >>> 0).toString(36);
-}

package/dist/orchestration/reactive-compact.js

@@ -1,78 +0,0 @@
-/**
- * Reactive Compact — Emergency context compression when API returns prompt-too-long.
- *
- * Aligned with Claude Code's reactive compact chain:
- * 1. API 413 → withhold error → attempt reactive compact → retry
- * 2. Only one reactive compact attempt per turn (prevent infinite loops)
- * 3. Falls back to abort if compact fails
- *
- * Also handles post-compact restoration:
- * - Todo list re-injection
- * - Skill context re-injection
- * - Tool delta re-injection (new/removed tools since last compact)
- */
-export const DEFAULT_REACTIVE_COMPACT_CONFIG = {
-    maxConsecutiveFailures: 3,
-    minMessagesAfterCompact: 4,
-    targetUsagePercent: 50,
-};
-/**
- * Build the restoration message to inject after a compact operation.
- * This ensures critical state survives context compression.
- */
-export function buildPostCompactRestorationMessage(payload) {
-    const sections = [];
-    if (payload.todoList && payload.todoList.length > 0) {
-        const todoLines = payload.todoList.map((t) => `  ${t.status === "completed" ? "[x]" : t.status === "in-progress" ? "[~]" : "[ ]"} #${t.id}: ${t.title}`);
-        sections.push(`## Active Todo List\n${todoLines.join("\n")}`);
-    }
-    if (payload.activeSkillContext) {
-        sections.push(`## Active Skill: ${payload.activeSkillContext.name}\nStep ${payload.activeSkillContext.step}:\n${payload.activeSkillContext.instructions}`);
-    }
-    if (payload.toolDelta && (payload.toolDelta.added.length > 0 || payload.toolDelta.removed.length > 0)) {
-        const lines = [];
-        if (payload.toolDelta.added.length > 0) {
-            lines.push(`New tools available: ${payload.toolDelta.added.join(", ")}`);
-        }
-        if (payload.toolDelta.removed.length > 0) {
-            lines.push(`Tools no longer available: ${payload.toolDelta.removed.join(", ")}`);
-        }
-        sections.push(`## Tool Changes\n${lines.join("\n")}`);
-    }
-    if (payload.customBlocks) {
-        for (const block of payload.customBlocks) {
-            sections.push(`## ${block.label}\n${block.content}`);
-        }
-    }
-    if (sections.length === 0)
-        return null;
-    return `[Context was compressed. The following state has been restored:]\n\n${sections.join("\n\n")}`;
-}
-export function createReactiveCompactState() {
-    return {
-        consecutiveFailures: 0,
-        attemptedThisTurn: false,
-        lastCompactAt: null,
-        toolsAtLastCompact: [],
-    };
-}
-/**
- * Determine if reactive compact should be attempted.
- */
-export function shouldAttemptReactiveCompact(state, config = DEFAULT_REACTIVE_COMPACT_CONFIG) {
-    if (state.attemptedThisTurn)
-        return false;
-    if (state.consecutiveFailures >= config.maxConsecutiveFailures)
-        return false;
-    return true;
-}
-/**
- * Calculate the tool delta since last compact.
- */
-export function computeToolDelta(currentTools, toolsAtLastCompact) {
-    const currentSet = new Set(currentTools);
-    const lastSet = new Set(toolsAtLastCompact);
-    const added = currentTools.filter((t) => !lastSet.has(t));
-    const removed = toolsAtLastCompact.filter((t) => !currentSet.has(t));
-    return { added, removed };
-}

package/dist/orchestration/retry-loop.js

@@ -1,24 +0,0 @@
-export async function executeBoundedRetryLoop(params) {
-    let iterations = 0;
-    while (true) {
-        if (iterations >= params.maxIterations) {
-            return await params.onRetryLimit({
-                iterations,
-                maxIterations: params.maxIterations,
-            });
-        }
-        iterations += 1;
-        const outcome = await params.executeIteration({ iteration: iterations });
-        if (outcome.kind === "return") {
-            return outcome.result;
-        }
-    }
-}
-export function resolveScaledRetryIterations(params) {
-    const baseIterations = Math.max(0, Math.floor(params.baseIterations ?? 24));
-    const perCandidateIterations = Math.max(0, Math.floor(params.perCandidateIterations ?? 8));
-    const minIterations = Math.max(1, Math.floor(params.minIterations ?? 32));
-    const maxIterations = Math.max(minIterations, Math.floor(params.maxIterations ?? 160));
-    const scaled = baseIterations + Math.max(1, Math.floor(params.candidateCount)) * perCandidateIterations;
-    return Math.min(maxIterations, Math.max(minIterations, scaled));
-}

package/dist/orchestration/skill-candidate.js

@@ -1,141 +0,0 @@
-import { coerceSkillCandidateJsonObject, normalizeSkillCandidateAction, normalizeSkillCandidateArtifact, normalizeSkillCandidateEffectiveness, normalizeSkillCandidateEffectivenessPhase, normalizeSkillCandidateSourceExecution, } from "../contracts/skill-candidate.js";
-const DEFAULT_SKILL_IMPROVEMENT_POLICY = {
-    reviewRequired: true,
-    canaryRequired: true,
-    autoPromote: false,
-    minCanarySampleCount: 10,
-    minSuccessRate: 0.7,
-    maxRegressionRate: 0.1,
-    maxCostIncreaseRate: 0.25,
-    staleAfterHours: 168,
-};
-function normalizeOptionalBoolean(value, fallback) {
-    if (typeof value === "boolean") {
-        return value;
-    }
-    if (typeof value === "string") {
-        const normalized = value.trim().toLowerCase();
-        if (normalized === "true") {
-            return true;
-        }
-        if (normalized === "false") {
-            return false;
-        }
-    }
-    return fallback;
-}
-function normalizeOptionalFiniteNumber(value, fallback) {
-    if (typeof value === "number" && Number.isFinite(value)) {
-        return value;
-    }
-    if (typeof value === "string") {
-        const trimmed = value.trim();
-        if (trimmed) {
-            const parsed = Number(trimmed);
-            if (Number.isFinite(parsed)) {
-                return parsed;
-            }
-        }
-    }
-    return fallback;
-}
-function normalizeOptionalStringArray(value) {
-    return Array.isArray(value)
-        ? value
-            .filter((entry) => typeof entry === "string")
-            .map((entry) => entry.trim())
-            .filter(Boolean)
-        : [];
-}
-export function createDefaultSkillImprovementPolicy(overrides = {}) {
-    return normalizeSkillImprovementPolicy(overrides, DEFAULT_SKILL_IMPROVEMENT_POLICY);
-}
-export function normalizeSkillImprovementPolicy(value, fallback = DEFAULT_SKILL_IMPROVEMENT_POLICY) {
-    const record = coerceSkillCandidateJsonObject(value);
-    return {
-        reviewRequired: normalizeOptionalBoolean(record.reviewRequired, fallback.reviewRequired),
-        canaryRequired: normalizeOptionalBoolean(record.canaryRequired, fallback.canaryRequired),
-        autoPromote: normalizeOptionalBoolean(record.autoPromote, fallback.autoPromote),
-        minCanarySampleCount: Math.max(1, Math.floor(normalizeOptionalFiniteNumber(record.minCanarySampleCount, fallback.minCanarySampleCount))),
-        minSuccessRate: Math.max(0, Math.min(1, normalizeOptionalFiniteNumber(record.minSuccessRate, fallback.minSuccessRate))),
-        maxRegressionRate: Math.max(0, Math.min(1, normalizeOptionalFiniteNumber(record.maxRegressionRate, fallback.maxRegressionRate))),
-        maxCostIncreaseRate: Math.max(0, normalizeOptionalFiniteNumber(record.maxCostIncreaseRate, fallback.maxCostIncreaseRate)),
-        staleAfterHours: Math.max(1, Math.floor(normalizeOptionalFiniteNumber(record.staleAfterHours, fallback.staleAfterHours))),
-    };
-}
-export function buildSkillCandidateEvidencePayload(params) {
-    const evidence = coerceSkillCandidateJsonObject(params.evidence);
-    const artifact = params.artifact ? normalizeSkillCandidateArtifact(params.artifact) : null;
-    const sourceExecution = params.sourceExecution
-        ? normalizeSkillCandidateSourceExecution(params.sourceExecution)
-        : null;
-    const sourceSessionKey = typeof params.sourceSessionKey === "string"
-        ? params.sourceSessionKey.trim()
-        : "";
-    return {
-        ...evidence,
-        ...(artifact ? { artifact } : {}),
-        ...(sourceExecution ? { sourceExecution } : {}),
-        ...(sourceSessionKey ? { sourceSessionKey } : {}),
-    };
-}
-export function buildSkillCandidateImprovementEvidenceBundle(params) {
-    const evidence = buildSkillCandidateEvidencePayload(params);
-    const diffSummary = typeof params.diffSummary === "string" && params.diffSummary.trim()
-        ? params.diffSummary.trim()
-        : "";
-    const baselineCandidateId = typeof params.baselineCandidateId === "string"
-        && params.baselineCandidateId.trim()
-        ? params.baselineCandidateId.trim()
-        : "";
-    const rolloutNotes = typeof params.rolloutNotes === "string" && params.rolloutNotes.trim()
-        ? params.rolloutNotes.trim()
-        : "";
-    const validationRefs = normalizeOptionalStringArray(params.validationRefs);
-    return {
-        ...evidence,
-        ...(diffSummary ? { diffSummary } : {}),
-        ...(baselineCandidateId ? { baselineCandidateId } : {}),
-        ...(rolloutNotes ? { rolloutNotes } : {}),
-        ...(validationRefs.length > 0 ? { validationRefs } : {}),
-    };
-}
-export function buildSkillCandidateLatestReview(params) {
-    return {
-        action: normalizeSkillCandidateAction(params.action) ?? params.action,
-        actor: typeof params.actor === "string" && params.actor.trim() ? params.actor.trim() : null,
-        notes: typeof params.notes === "string" && params.notes.trim() ? params.notes.trim() : null,
-        payload: coerceSkillCandidateJsonObject(params.payload),
-        createdAt: typeof params.createdAt === "string" && params.createdAt.trim()
-            ? params.createdAt.trim()
-            : new Date().toISOString(),
-    };
-}
-export function buildSkillCandidateEffectivenessSummary(params) {
-    const sampleCount = Math.max(0, Math.floor(params.sampleCount ?? 0));
-    const successCount = Math.max(0, Math.floor(params.successCount ?? 0));
-    const failureCount = Math.max(0, Math.floor(params.failureCount ?? Math.max(sampleCount - successCount, 0)));
-    const regressionCount = Math.max(0, Math.floor(params.regressionCount ?? 0));
-    const successRate = sampleCount > 0 ? successCount / sampleCount : 0;
-    const regressionRate = sampleCount > 0 ? regressionCount / sampleCount : 0;
-    const score = typeof params.score === "number" && Number.isFinite(params.score)
-        ? params.score
-        : Number((successRate - regressionRate).toFixed(4));
-    return normalizeSkillCandidateEffectiveness({
-        phase: normalizeSkillCandidateEffectivenessPhase(params.phase) ?? params.phase,
-        sampleCount,
-        successCount,
-        failureCount,
-        regressionCount,
-        successRate,
-        regressionRate,
-        avgLatencyMs: params.avgLatencyMs,
-        avgCostUsd: params.avgCostUsd,
-        score,
-        staleReason: params.staleReason,
-        notes: params.notes,
-        summary: coerceSkillCandidateJsonObject(params.summary),
-        lastObservedAt: params.lastObservedAt ?? new Date().toISOString(),
-        updatedAt: params.updatedAt ?? new Date().toISOString(),
-    });
-}