@cleocode/lafs 1.8.0

package/dist/src/a2a/task-lifecycle.js

@@ -0,0 +1,313 @@
+/**
+ * A2A Task Lifecycle Management
+ *
+ * State machine enforcement, task CRUD, and LAFS integration
+ * for A2A Protocol v1.0+ compliance.
+ *
+ * Reference: A2A spec Section 6 (Task Lifecycle)
+ */
+import { createLafsArtifact } from './bridge.js';
+// ============================================================================
+// State Constants
+// ============================================================================
+/** States from which no further transitions are possible */
+export const TERMINAL_STATES = new Set([
+    'completed',
+    'failed',
+    'canceled',
+    'rejected',
+]);
+/** States where the task is paused awaiting external input */
+export const INTERRUPTED_STATES = new Set([
+    'input-required',
+    'auth-required',
+]);
+/** Valid state transitions (adjacency map). Terminal states have empty outgoing sets. */
+export const VALID_TRANSITIONS = new Map([
+    ['submitted', new Set(['working', 'canceled', 'rejected', 'failed'])],
+    ['working', new Set(['completed', 'failed', 'canceled', 'input-required', 'auth-required'])],
+    ['input-required', new Set(['working', 'canceled', 'failed'])],
+    ['auth-required', new Set(['working', 'canceled', 'failed'])],
+    ['completed', new Set()],
+    ['failed', new Set()],
+    ['canceled', new Set()],
+    ['rejected', new Set()],
+    ['unknown', new Set(['submitted', 'working', 'input-required', 'completed', 'canceled', 'failed', 'rejected', 'auth-required'])],
+]);
+// ============================================================================
+// State Functions
+// ============================================================================
+/** Check if a transition from one state to another is valid */
+export function isValidTransition(from, to) {
+    const allowed = VALID_TRANSITIONS.get(from);
+    return allowed ? allowed.has(to) : false;
+}
+/** Check if a state is terminal (no further transitions allowed) */
+export function isTerminalState(state) {
+    return TERMINAL_STATES.has(state);
+}
+/** Check if a state is interrupted (paused awaiting input) */
+export function isInterruptedState(state) {
+    return INTERRUPTED_STATES.has(state);
+}
+// ============================================================================
+// Error Classes
+// ============================================================================
+/** Thrown when attempting an invalid state transition */
+export class InvalidStateTransitionError extends Error {
+    taskId;
+    fromState;
+    toState;
+    constructor(taskId, fromState, toState) {
+        super(`Invalid transition for task ${taskId}: ${fromState} -> ${toState}`);
+        this.name = 'InvalidStateTransitionError';
+        this.taskId = taskId;
+        this.fromState = fromState;
+        this.toState = toState;
+    }
+}
+/** Thrown when attempting to modify a task in a terminal state */
+export class TaskImmutabilityError extends Error {
+    taskId;
+    terminalState;
+    constructor(taskId, terminalState) {
+        super(`Task ${taskId} is in terminal state ${terminalState} and cannot be modified`);
+        this.name = 'TaskImmutabilityError';
+        this.taskId = taskId;
+        this.terminalState = terminalState;
+    }
+}
+/** Thrown when a task is not found */
+export class TaskNotFoundError extends Error {
+    taskId;
+    constructor(taskId) {
+        super(`Task not found: ${taskId}`);
+        this.name = 'TaskNotFoundError';
+        this.taskId = taskId;
+    }
+}
+/** Thrown when a refinement/follow-up task references invalid parent tasks */
+export class TaskRefinementError extends Error {
+    referenceTaskIds;
+    constructor(message, referenceTaskIds) {
+        super(message);
+        this.name = 'TaskRefinementError';
+        this.referenceTaskIds = referenceTaskIds;
+    }
+}
+// ============================================================================
+// ID Generation
+// ============================================================================
+function generateId() {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+/**
+ * In-memory task manager implementing A2A task lifecycle.
+ * Enforces valid state transitions and terminal state immutability.
+ */
+export class TaskManager {
+    tasks = new Map();
+    contextIndex = new Map();
+    /** Create a new task in the submitted state */
+    createTask(options) {
+        const id = generateId();
+        const resolvedContextId = options?.contextId ?? this.resolveContextForReferenceTasks(options?.referenceTaskIds) ?? generateId();
+        const contextId = resolvedContextId;
+        const referenceTaskIds = options?.referenceTaskIds ?? [];
+        this.validateReferenceTasks(referenceTaskIds, contextId);
+        const metadata = {
+            ...(options?.metadata ?? {}),
+            ...(referenceTaskIds.length > 0 ? { referenceTaskIds } : {}),
+            ...(options?.parallelFollowUp ? { parallelFollowUp: true } : {}),
+        };
+        const task = {
+            id,
+            contextId,
+            kind: 'task',
+            status: {
+                state: 'submitted',
+                timestamp: new Date().toISOString(),
+            },
+            ...(Object.keys(metadata).length > 0 && { metadata }),
+        };
+        this.tasks.set(id, task);
+        // Index by contextId
+        let contextTasks = this.contextIndex.get(contextId);
+        if (!contextTasks) {
+            contextTasks = new Set();
+            this.contextIndex.set(contextId, contextTasks);
+        }
+        contextTasks.add(id);
+        return structuredClone(task);
+    }
+    /** Create a refinement/follow-up task referencing existing task(s). */
+    createRefinedTask(referenceTaskIds, options) {
+        return this.createTask({
+            ...options,
+            referenceTaskIds,
+            parallelFollowUp: options?.parallelFollowUp,
+        });
+    }
+    /** Get a task by ID. Throws TaskNotFoundError if not found. */
+    getTask(taskId) {
+        const task = this.tasks.get(taskId);
+        if (!task) {
+            throw new TaskNotFoundError(taskId);
+        }
+        return structuredClone(task);
+    }
+    /** List tasks with optional filtering and pagination */
+    listTasks(options) {
+        let taskIds;
+        if (options?.contextId) {
+            const contextTasks = this.contextIndex.get(options.contextId);
+            taskIds = contextTasks ? [...contextTasks] : [];
+        }
+        else {
+            taskIds = [...this.tasks.keys()];
+        }
+        // Filter by state
+        if (options?.state) {
+            taskIds = taskIds.filter(id => {
+                const task = this.tasks.get(id);
+                return task && task.status.state === options.state;
+            });
+        }
+        // Sort for deterministic pagination
+        taskIds.sort();
+        // Apply page token (cursor-based: token is the last seen task ID)
+        if (options?.pageToken) {
+            const startIdx = taskIds.indexOf(options.pageToken);
+            if (startIdx >= 0) {
+                taskIds = taskIds.slice(startIdx + 1);
+            }
+        }
+        // Apply limit
+        const limit = options?.limit ?? taskIds.length;
+        const pageTaskIds = taskIds.slice(0, limit);
+        const hasMore = taskIds.length > limit;
+        const tasks = pageTaskIds.map(id => structuredClone(this.tasks.get(id)));
+        const nextPageToken = hasMore ? pageTaskIds[pageTaskIds.length - 1] : undefined;
+        return { tasks, nextPageToken };
+    }
+    /**
+     * Update task status. Enforces valid transitions and terminal state immutability.
+     * @throws InvalidStateTransitionError if the transition is not valid
+     * @throws TaskImmutabilityError if the task is in a terminal state
+     */
+    updateTaskStatus(taskId, state, message) {
+        const task = this.tasks.get(taskId);
+        if (!task) {
+            throw new TaskNotFoundError(taskId);
+        }
+        const currentState = task.status.state;
+        if (isTerminalState(currentState)) {
+            throw new TaskImmutabilityError(taskId, currentState);
+        }
+        if (!isValidTransition(currentState, state)) {
+            throw new InvalidStateTransitionError(taskId, currentState, state);
+        }
+        const status = {
+            state,
+            timestamp: new Date().toISOString(),
+            ...(message && { message }),
+        };
+        task.status = status;
+        return structuredClone(task);
+    }
+    /**
+     * Add an artifact to a task.
+     * @throws TaskImmutabilityError if the task is in a terminal state
+     */
+    addArtifact(taskId, artifact) {
+        const task = this.tasks.get(taskId);
+        if (!task) {
+            throw new TaskNotFoundError(taskId);
+        }
+        if (isTerminalState(task.status.state)) {
+            throw new TaskImmutabilityError(taskId, task.status.state);
+        }
+        if (!task.artifacts) {
+            task.artifacts = [];
+        }
+        task.artifacts.push(artifact);
+        return structuredClone(task);
+    }
+    /**
+     * Add a message to task history.
+     * @throws TaskImmutabilityError if the task is in a terminal state
+     */
+    addHistory(taskId, message) {
+        const task = this.tasks.get(taskId);
+        if (!task) {
+            throw new TaskNotFoundError(taskId);
+        }
+        if (isTerminalState(task.status.state)) {
+            throw new TaskImmutabilityError(taskId, task.status.state);
+        }
+        if (!task.history) {
+            task.history = [];
+        }
+        task.history.push(message);
+        return structuredClone(task);
+    }
+    /** Cancel a task by transitioning to canceled state */
+    cancelTask(taskId) {
+        return this.updateTaskStatus(taskId, 'canceled');
+    }
+    /** Get all tasks in a given context */
+    getTasksByContext(contextId) {
+        const taskIds = this.contextIndex.get(contextId);
+        if (!taskIds)
+            return [];
+        return [...taskIds].map(id => structuredClone(this.tasks.get(id)));
+    }
+    /** Check if a task is in a terminal state */
+    isTerminal(taskId) {
+        const task = this.tasks.get(taskId);
+        if (!task) {
+            throw new TaskNotFoundError(taskId);
+        }
+        return isTerminalState(task.status.state);
+    }
+    resolveContextForReferenceTasks(referenceTaskIds) {
+        if (!referenceTaskIds || referenceTaskIds.length === 0) {
+            return undefined;
+        }
+        const firstId = referenceTaskIds[0];
+        if (!firstId) {
+            return undefined;
+        }
+        const first = this.tasks.get(firstId);
+        return first?.contextId;
+    }
+    validateReferenceTasks(referenceTaskIds, contextId) {
+        if (referenceTaskIds.length === 0) {
+            return;
+        }
+        for (const refId of referenceTaskIds) {
+            const refTask = this.tasks.get(refId);
+            if (!refTask) {
+                throw new TaskRefinementError(`Referenced task not found: ${refId}`, referenceTaskIds);
+            }
+            if (refTask.contextId !== contextId) {
+                throw new TaskRefinementError(`Referenced task ${refId} has different contextId (${refTask.contextId}) than refinement (${contextId})`, referenceTaskIds);
+            }
+        }
+    }
+}
+// ============================================================================
+// LAFS Integration
+// ============================================================================
+/**
+ * Attach a LAFS envelope as an artifact to an A2A task.
+ * Uses createLafsArtifact() from bridge.ts to wrap the envelope.
+ */
+export function attachLafsEnvelope(manager, taskId, envelope) {
+    const artifact = createLafsArtifact(envelope);
+    return manager.addArtifact(taskId, artifact);
+}

package/dist/src/budgetEnforcement.d.ts

@@ -0,0 +1,84 @@
+/**
+ * LAFS Budget Enforcement
+ *
+ * Middleware for enforcing MVI (Minimal Viable Interface) token budgets on LAFS envelopes.
+ * Provides budget checking, truncation, and error generation for exceeded budgets.
+ */
+import type { LAFSEnvelope } from "./types.js";
+import type { BudgetEnforcementOptions, TokenEstimate, BudgetEnforcementResult } from "./types.js";
+import { TokenEstimator } from "./tokenEstimator.js";
+/**
+ * Budget exceeded error code from LAFS error registry
+ */
+declare const BUDGET_EXCEEDED_CODE = "E_MVI_BUDGET_EXCEEDED";
+/**
+ * Apply budget enforcement to an envelope.
+ *
+ * @param envelope - The LAFS envelope to check
+ * @param budget - Maximum allowed tokens
+ * @param options - Budget enforcement options
+ * @returns Enforce result with potentially modified envelope
+ */
+export declare function applyBudgetEnforcement(envelope: LAFSEnvelope, budget: number, options?: BudgetEnforcementOptions): BudgetEnforcementResult;
+/**
+ * Type for middleware function
+ */
+type EnvelopeMiddleware = (envelope: LAFSEnvelope, next: () => LAFSEnvelope | Promise<LAFSEnvelope>) => Promise<LAFSEnvelope> | LAFSEnvelope;
+/**
+ * Create a budget enforcement middleware function.
+ *
+ * @param budget - Maximum allowed tokens for response
+ * @param options - Budget enforcement options
+ * @returns Middleware function that enforces budget
+ *
+ * @example
+ * ```typescript
+ * const middleware = withBudget(1000, { truncateOnExceed: true });
+ * const result = await middleware(envelope, async () => nextEnvelope);
+ * ```
+ */
+export declare function withBudget(budget: number, options?: BudgetEnforcementOptions): EnvelopeMiddleware;
+/**
+ * Check if an envelope has exceeded its budget without modifying it.
+ *
+ * @param envelope - The LAFS envelope to check
+ * @param budget - Maximum allowed tokens
+ * @returns Budget check result
+ */
+export declare function checkBudget(envelope: LAFSEnvelope, budget: number): {
+    exceeded: boolean;
+    estimated: number;
+    remaining: number;
+};
+/**
+ * Synchronous version of withBudget for non-async contexts.
+ *
+ * @param budget - Maximum allowed tokens for response
+ * @param options - Budget enforcement options
+ * @returns Middleware function that enforces budget synchronously
+ */
+export declare function withBudgetSync(budget: number, options?: BudgetEnforcementOptions): (envelope: LAFSEnvelope, next: () => LAFSEnvelope) => LAFSEnvelope;
+/**
+ * Higher-order function that wraps a handler with budget enforcement.
+ *
+ * @param handler - The handler function to wrap
+ * @param budget - Maximum allowed tokens
+ * @param options - Budget enforcement options
+ * @returns Wrapped handler with budget enforcement
+ *
+ * @example
+ * ```typescript
+ * const myHandler = async (request: Request) => ({ success: true, result: { data } });
+ * const budgetedHandler = wrapWithBudget(myHandler, 1000, { truncateOnExceed: true });
+ * const result = await budgetedHandler(request);
+ * ```
+ */
+export declare function wrapWithBudget<TArgs extends unknown[], TResult extends LAFSEnvelope>(handler: (...args: TArgs) => TResult | Promise<TResult>, budget: number, options?: BudgetEnforcementOptions): (...args: TArgs) => Promise<LAFSEnvelope>;
+/**
+ * Compose multiple middleware functions into a single middleware.
+ * Middleware is executed in order (left to right).
+ */
+export declare function composeMiddleware(...middlewares: EnvelopeMiddleware[]): EnvelopeMiddleware;
+export type { BudgetEnforcementOptions, TokenEstimate, BudgetEnforcementResult };
+export { TokenEstimator };
+export { BUDGET_EXCEEDED_CODE };