@lumenflow/agent 1.3.2 → 1.3.4

package/dist/agent-incidents.d.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+/**
+ * IncidentLog schema for structured issue tracking
+ * Stored as NDJSON in .beacon/incidents/<category>.ndjson
+ */
+export declare const IncidentLogSchema: z.ZodObject<{
+    timestamp: z.ZodString;
+    session_id: z.ZodString;
+    wu_id: z.ZodString;
+    lane: z.ZodString;
+    category: z.ZodEnum<{
+        workflow: "workflow";
+        tooling: "tooling";
+        confusion: "confusion";
+        violation: "violation";
+        error: "error";
+    }>;
+    severity: z.ZodEnum<{
+        blocker: "blocker";
+        major: "major";
+        minor: "minor";
+        info: "info";
+    }>;
+    title: z.ZodString;
+    description: z.ZodString;
+    resolution: z.ZodOptional<z.ZodString>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    context: z.ZodDefault<z.ZodOptional<z.ZodObject<{
+        git_branch: z.ZodOptional<z.ZodString>;
+        current_step: z.ZodOptional<z.ZodString>;
+        related_files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/**
+ * @typedef {z.infer<typeof IncidentLogSchema>} IncidentLog
+ */
+/**
+ * Inferred type from IncidentLogSchema
+ */
+export type IncidentLog = z.infer<typeof IncidentLogSchema>;
+/**
+ * Append an incident to the appropriate NDJSON log file
+ * @param incident - Incident data (will be validated)
+ * @param incidentsDir - Optional directory override (for testing)
+ * @throws {z.ZodError} if incident data is invalid
+ */
+export declare function appendIncident(incident: unknown, incidentsDir?: string): void;
+/**
+ * Read and parse incidents from NDJSON files
+ * @param categories - Categories to read (default: all)
+ * @param since - Filter incidents after this date
+ * @param incidentsDir - Optional directory override (for testing)
+ * @returns Parsed and validated incidents
+ */
+export declare function readIncidents(categories?: readonly string[] | null, since?: Date | null, incidentsDir?: string): IncidentLog[];

package/dist/agent-session.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Session data structure
+ */
+interface SessionData {
+    session_id: string;
+    wu_id: string;
+    lane: string;
+    started: string;
+    completed?: string;
+    agent_type: string;
+    context_tier: number;
+    incidents_logged: number;
+    incidents_major: number;
+}
+/**
+ * Start a new agent session
+ * @param wuId - WU ID (e.g., "WU-1234")
+ * @param tier - Context tier from bootloader
+ * @param agentType - Agent type (default: "claude-code")
+ * @returns session_id
+ * @throws {Error} if session already active or WU format invalid
+ */
+export declare function startSession(wuId: string, tier: 1 | 2 | 3, agentType?: string): Promise<string>;
+/**
+ * Get the current active session
+ * @returns Session state or null if no active session
+ */
+export declare function getCurrentSession(): Promise<SessionData | null>;
+/**
+ * Incident data input type
+ */
+interface IncidentDataInput {
+    category: string;
+    severity: string;
+    title: string;
+    description: string;
+    context?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Log an incident and update session counters
+ * @param incidentData - Incident data (category, severity, title, description, etc.)
+ * @throws {Error} if no active session
+ */
+export declare function logIncident(incidentData: IncidentDataInput): Promise<void>;
+/**
+ * Session summary returned after ending a session
+ */
+interface SessionSummary {
+    wu_id: string;
+    lane: string;
+    session_id: string;
+    started: string;
+    completed: string;
+    agent_type: string;
+    context_tier: number;
+    incidents_logged: number;
+    incidents_major: number;
+}
+/**
+ * End the current session and return summary
+ * @returns Session summary for appending to WU YAML
+ * @throws {Error} if no active session
+ */
+export declare function endSession(): Promise<SessionSummary>;
+export {};

package/dist/agent-verification.d.ts

@@ -0,0 +1,31 @@
+type RunFn = (cmd: string) => string;
+type ExistsFn = (path: string) => boolean;
+/**
+ * Verification result type
+ */
+export interface VerificationResult {
+    complete: boolean;
+    failures: string[];
+}
+/**
+ * Verification overrides for testing
+ */
+interface VerificationOverrides {
+    run?: RunFn;
+    exists?: ExistsFn;
+}
+/**
+ * Verify that a WU has been completed and merged to main.
+ *
+ * Checks:
+ *   1. Working tree is clean
+ *   2. Completion stamp exists
+ *   3. Main history contains a commit updating the WU YAML
+ *
+ * @param wuId - Work Unit identifier (e.g., "WU-510")
+ * @param overrides - Test overrides
+ * @returns Verification result
+ */
+export declare function verifyWUComplete(wuId: string, overrides?: VerificationOverrides): VerificationResult;
+export declare function debugSummary(result: VerificationResult | null | undefined): string;
+export {};

package/dist/auto-session-integration.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Session data stored in current.json
+ */
+interface SessionFileData {
+    session_id: string;
+    wu_id: string;
+    started: string;
+    completed?: string;
+    agent_type: string;
+    context_tier: number;
+    incidents_logged: number;
+    incidents_major: number;
+    auto_started?: boolean;
+}
+/**
+ * Options for starting a session for a WU
+ */
+interface StartSessionOptions {
+    wuId: string;
+    tier?: 1 | 2 | 3;
+    agentType?: string;
+    sessionDir?: string;
+    baseDir?: string;
+}
+/**
+ * Result of starting a session
+ */
+interface StartSessionResult {
+    sessionId: string;
+    alreadyActive?: boolean;
+    memoryNodeId?: string | null;
+}
+/**
+ * Start a session for a WU (called by wu:claim)
+ *
+ * Unlike startSession in agent-session.mjs, this function:
+ * - Does NOT throw if a session already exists (returns existing session)
+ * - Uses default tier 2 if not specified
+ * - Supports custom session directory for testing
+ * - Creates memory layer session node for context restoration (WU-1466)
+ *
+ * @param options - Session options
+ * @returns Session result
+ */
+export declare function startSessionForWU(options: StartSessionOptions): Promise<StartSessionResult>;
+/**
+ * Options for ending a session
+ */
+interface EndSessionOptions {
+    sessionDir?: string;
+}
+/**
+ * Session summary
+ */
+interface SessionSummary {
+    wu_id: string;
+    session_id: string;
+    started: string;
+    completed: string;
+    agent_type: string;
+    context_tier: number;
+    incidents_logged: number;
+    incidents_major: number;
+}
+/**
+ * Result of ending a session
+ */
+interface EndSessionResult {
+    ended: boolean;
+    summary?: SessionSummary;
+    reason?: string;
+}
+/**
+ * End the current session (called by wu:done)
+ *
+ * Unlike endSession in agent-session.mjs, this function:
+ * - Does NOT throw if no active session (returns { ended: false })
+ * - Returns structured result with summary
+ * - Supports custom session directory for testing
+ *
+ * @param options - Session options
+ * @returns Session end result
+ */
+export declare function endSessionForWU(options?: EndSessionOptions): EndSessionResult;
+/**
+ * Options for getting current session
+ */
+interface GetSessionOptions {
+    sessionDir?: string;
+}
+/**
+ * Get the current active session
+ *
+ * @param options - Session options
+ * @returns Session object or null if no active session
+ */
+export declare function getCurrentSessionForWU(options?: GetSessionOptions): SessionFileData | null;
+/**
+ * Check if there's an active session for a specific WU
+ *
+ * @param wuId - WU ID to check
+ * @param options - Session options
+ * @returns True if session exists and matches WU ID
+ */
+export declare function hasActiveSessionForWU(wuId: string, options?: GetSessionOptions): boolean;
+export {};

package/dist/feedback-promote-core.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Feedback Promote Core Logic (WU-1599)
+ *
+ * Generates draft WU specs from feedback patterns and promotes them to actual WUs.
+ * Tracks incident-to-WU mappings in feedback-index.ndjson.
+ *
+ * @see {@link tools/__tests__/feedback-promote.test.mjs} - Tests
+ * @see {@link tools/feedback-promote.mjs} - CLI entry point
+ */
+/**
+ * Directory for draft WU specs
+ */
+export declare const DRAFT_DIRECTORY = ".beacon/feedback-drafts";
+/**
+ * Path to feedback index (incident-to-WU mappings)
+ */
+export declare const FEEDBACK_INDEX_PATH = ".beacon/feedback-index.ndjson";
+/**
+ * Feedback index entry status
+ */
+export declare const FEEDBACK_STATUS: {
+    PENDING_RESOLUTION: string;
+    RESOLVED: string;
+    WONT_FIX: string;
+};
+/**
+ * Pattern example structure
+ */
+interface PatternExample {
+    id: string;
+    [key: string]: unknown;
+}
+/**
+ * Pattern structure from feedback:review
+ */
+interface Pattern {
+    title: string;
+    category?: string;
+    frequency?: number;
+    score?: number;
+    firstSeen?: string;
+    lastSeen?: string;
+    examples?: PatternExample[];
+}
+/**
+ * Draft WU spec structure
+ */
+interface DraftSpec {
+    title: string;
+    lane: string;
+    description: string;
+    acceptance: string[];
+    source_incidents: string[];
+    pattern_metadata: {
+        frequency: number | undefined;
+        category: string | undefined;
+        score: number | undefined;
+        firstSeen: string | undefined;
+        lastSeen: string | undefined;
+    };
+    filePath?: string;
+}
+/**
+ * Options for generating a draft
+ */
+interface GenerateDraftOptions {
+    writeFile?: boolean;
+}
+/**
+ * Generate draft WU spec from a pattern
+ *
+ * @param baseDir - Base directory
+ * @param pattern - Pattern from feedback:review
+ * @param options - Options
+ * @returns Draft WU spec
+ */
+export declare function generateDraft(baseDir: string, pattern: Pattern, options?: GenerateDraftOptions): Promise<DraftSpec>;
+/**
+ * Load all draft files from .beacon/feedback-drafts/
+ *
+ * @param baseDir - Base directory
+ * @returns Array of draft objects with filePath
+ */
+export declare function loadDrafts(baseDir: string): Promise<DraftSpec[]>;
+/**
+ * Options for promoting a draft
+ */
+interface PromoteDraftOptions {
+    dryRun?: boolean;
+    wuIdOverride?: string;
+    removeDraft?: boolean;
+}
+/**
+ * Result of promoting a draft
+ */
+interface PromoteDraftResult {
+    success: boolean;
+    wuId: string;
+    command: string;
+    draft?: DraftSpec;
+    error?: string;
+    draftRemoved?: boolean;
+}
+/**
+ * Promote a draft to a WU via wu:create
+ *
+ * @param baseDir - Base directory
+ * @param draft - Draft object
+ * @param options - Options
+ * @returns Result with success, wuId, command
+ */
+export declare function promoteDraft(baseDir: string, draft: DraftSpec, options?: PromoteDraftOptions): Promise<PromoteDraftResult>;
+/**
+ * Feedback index entry
+ */
+interface FeedbackIndexEntry {
+    incident_id: string;
+    wu_id: string;
+    status: string;
+    timestamp: string;
+}
+/**
+ * Update feedback index with incident-to-WU mappings
+ *
+ * @param baseDir - Base directory
+ * @param wuId - WU ID
+ * @param incidentIds - Array of incident IDs
+ */
+export declare function updateFeedbackIndex(baseDir: string, wuId: string, incidentIds: string[]): Promise<void>;
+/**
+ * Load feedback index entries
+ *
+ * @param baseDir - Base directory
+ * @returns Array of index entries
+ */
+export declare function loadFeedbackIndex(baseDir: string): Promise<FeedbackIndexEntry[]>;
+export {};

package/dist/feedback-review-core.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Feedback Review Core Logic (WU-1598)
+ *
+ * Aggregates .beacon/incidents/*.ndjson and .beacon/memory/memory.jsonl,
+ * clusters by title similarity, scores patterns (frequency x severity x recency),
+ * and outputs prioritised patterns for human review.
+ *
+ * @see {@link tools/__tests__/feedback-review.test.mjs} - Tests
+ * @see {@link tools/feedback-review.mjs} - CLI entry point
+ */
+import { INCIDENT_SEVERITY } from '@lumenflow/core/lib/wu-constants.js';
+/**
+ * Severity weights for scoring
+ *
+ * Higher severity = higher weight in scoring formula
+ */
+export declare const SEVERITY_WEIGHTS: {
+    [INCIDENT_SEVERITY.BLOCKER]: number;
+    [INCIDENT_SEVERITY.MAJOR]: number;
+    [INCIDENT_SEVERITY.MINOR]: number;
+    [INCIDENT_SEVERITY.INFO]: number;
+};
+/**
+ * Node with ID and optional title/content
+ */
+interface NodeWithTitle {
+    id: string;
+    title?: string;
+    content?: string;
+    category?: string;
+    severity?: string;
+    created_at?: string;
+    source?: string;
+    metadata?: Record<string, unknown>;
+    type?: string;
+    tags?: string[];
+}
+/**
+ * Cluster of nodes grouped by title similarity
+ */
+interface Cluster {
+    title: string;
+    nodes: NodeWithTitle[];
+    category: string;
+}
+/**
+ * Cluster nodes by title similarity
+ *
+ * Uses simple greedy clustering with Jaccard similarity.
+ *
+ * @param nodes - Nodes to cluster
+ * @param threshold - Similarity threshold
+ * @returns Array of cluster objects
+ */
+export declare function clusterByTitle(nodes: NodeWithTitle[], threshold?: number): Cluster[];
+/**
+ * Score a pattern cluster
+ *
+ * Formula: frequency x average_severity x recency_factor
+ *
+ * @param cluster - Cluster with nodes
+ * @returns Score value
+ */
+export declare function scorePattern(cluster: Cluster): number;
+/**
+ * Options for reviewing feedback
+ */
+interface ReviewOptions {
+    since?: string;
+    minFrequency?: number;
+    category?: string;
+    json?: boolean;
+}
+/**
+ * Pattern example for output
+ */
+interface PatternExample {
+    id: string;
+    severity: string | undefined;
+    source: string | undefined;
+}
+/**
+ * Pattern in review result
+ */
+interface ReviewPattern {
+    title: string;
+    frequency: number;
+    category: string;
+    score: number;
+    firstSeen: string | undefined;
+    lastSeen: string | undefined;
+    examples: PatternExample[];
+}
+/**
+ * Review result
+ */
+interface ReviewResult {
+    success: boolean;
+    patterns: ReviewPattern[];
+    summary: {
+        totalNodes: number;
+        totalClusters: number;
+        topCategory: string | null;
+    };
+}
+/**
+ * Review feedback from incidents and memory nodes
+ *
+ * Main entry point for feedback review logic.
+ *
+ * @param baseDir - Base directory containing .beacon
+ * @param options - Review options
+ * @returns Review result
+ */
+export declare function reviewFeedback(baseDir: string, options?: ReviewOptions): Promise<ReviewResult>;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @lumenflow/agent - Agent session management
+ * @module @lumenflow/agent
+ */
+export * from './agent-incidents.js';
+export * from './agent-session.js';
+export * from './agent-verification.js';
+export * from './auto-session-integration.js';
+export * from './feedback-promote-core.js';
+export * from './feedback-review-core.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/agent",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "description": "Agent session management for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -40,8 +40,8 @@
   "dependencies": {
     "simple-git": "^3.30.0",
     "zod": "^4.3.5",
-    "@lumenflow/core": "1.3.2",
-    "@lumenflow/memory": "1.3.2"
+    "@lumenflow/memory": "1.3.4",
+    "@lumenflow/core": "1.3.4"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.17",