@lumenflow/agent 1.0.0

package/dist/agent-session.js

@@ -0,0 +1,155 @@
+import { randomUUID } from 'crypto';
+import { readFile, writeFile, mkdir, unlink, access } from 'node:fs/promises';
+import { join } from 'path';
+import { simpleGit } from 'simple-git';
+import { appendIncident } from './agent-incidents.js';
+import { PATTERNS, INCIDENT_SEVERITY, BEACON_PATHS } from '@lumenflow/core/lib/wu-constants.js';
+const SESSION_DIR = BEACON_PATHS.SESSIONS;
+const SESSION_FILE = join(SESSION_DIR, 'current.json');
+/**
+ * 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 async function startSession(wuId, tier, agentType = 'claude-code') {
+    // Check for existing session
+    const sessionExists = await access(SESSION_FILE)
+        .then(() => true)
+        .catch(() => false);
+    if (sessionExists) {
+        const content = await readFile(SESSION_FILE, { encoding: 'utf-8' });
+        const existing = JSON.parse(content);
+        throw new Error(`Session ${existing.session_id} already active for ${existing.wu_id}. ` +
+            `Run 'pnpm agent:session:end' first.`);
+    }
+    // Validate WU ID format
+    if (!PATTERNS.WU_ID.test(wuId)) {
+        throw new Error(`Invalid WU ID format: ${wuId}. Must match WU-XXX.`);
+    }
+    // Validate tier
+    if (![1, 2, 3].includes(tier)) {
+        throw new Error(`Invalid context tier: ${tier}. Must be 1, 2, or 3.`);
+    }
+    // Auto-detect lane from git branch if possible
+    const git = simpleGit();
+    let lane = 'Unknown';
+    try {
+        const branch = await git.revparse(['--abbrev-ref', 'HEAD']);
+        // Parse lane from branch name: lane/<lane>/wu-xxx → <lane>
+        const match = branch.match(/^lane\/([^/]+)\//);
+        if (match) {
+            lane = match[1]
+                .split('-')
+                .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+                .join(': ');
+        }
+    }
+    catch {
+        // Fallback: lane stays "Unknown"
+    }
+    const sessionId = randomUUID();
+    const session = {
+        session_id: sessionId,
+        wu_id: wuId,
+        lane,
+        started: new Date().toISOString(),
+        agent_type: agentType,
+        context_tier: tier,
+        incidents_logged: 0,
+        incidents_major: 0,
+    };
+    // Ensure directory exists
+    const dirExists = await access(SESSION_DIR)
+        .then(() => true)
+        .catch(() => false);
+    if (!dirExists) {
+        await mkdir(SESSION_DIR, { recursive: true });
+    }
+    await writeFile(SESSION_FILE, JSON.stringify(session, null, 2));
+    return sessionId;
+}
+/**
+ * Get the current active session
+ * @returns Session state or null if no active session
+ */
+export async function getCurrentSession() {
+    const sessionExists = await access(SESSION_FILE)
+        .then(() => true)
+        .catch(() => false);
+    if (!sessionExists)
+        return null;
+    const content = await readFile(SESSION_FILE, { encoding: 'utf-8' });
+    return JSON.parse(content);
+}
+/**
+ * Log an incident and update session counters
+ * @param incidentData - Incident data (category, severity, title, description, etc.)
+ * @throws {Error} if no active session
+ */
+export async function logIncident(incidentData) {
+    const session = await getCurrentSession();
+    if (!session) {
+        throw new Error('No active session. Run: pnpm agent:session start --wu WU-XXX --tier N');
+    }
+    // Get current git context
+    const git = simpleGit();
+    let gitBranch = 'unknown';
+    try {
+        gitBranch = await git.revparse(['--abbrev-ref', 'HEAD']);
+    }
+    catch {
+        // Ignore git errors
+    }
+    // Build full incident record
+    const incident = {
+        timestamp: new Date().toISOString(),
+        session_id: session.session_id,
+        wu_id: session.wu_id,
+        lane: session.lane,
+        ...incidentData,
+        context: {
+            git_branch: gitBranch,
+            ...(incidentData.context ?? {}),
+        },
+    };
+    // Append to NDJSON (will validate)
+    appendIncident(incident);
+    // Update session counters
+    session.incidents_logged++;
+    if (incident.severity === INCIDENT_SEVERITY.MAJOR ||
+        incident.severity === INCIDENT_SEVERITY.BLOCKER) {
+        session.incidents_major++;
+    }
+    await writeFile(SESSION_FILE, JSON.stringify(session, null, 2));
+}
+/**
+ * End the current session and return summary
+ * @returns Session summary for appending to WU YAML
+ * @throws {Error} if no active session
+ */
+export async function endSession() {
+    const session = await getCurrentSession();
+    if (!session) {
+        throw new Error('No active session to end.');
+    }
+    // Finalize session
+    session.completed = new Date().toISOString();
+    // Clean up session file
+    await unlink(SESSION_FILE);
+    // Return session object for WU YAML
+    return {
+        wu_id: session.wu_id,
+        lane: session.lane,
+        session_id: session.session_id,
+        started: session.started,
+        completed: session.completed,
+        agent_type: session.agent_type,
+        context_tier: session.context_tier,
+        incidents_logged: session.incidents_logged,
+        incidents_major: session.incidents_major,
+        // artifacts can be added manually later
+    };
+}

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/agent-verification.js

@@ -0,0 +1,118 @@
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createError, ErrorCodes } from '@lumenflow/core/lib/error-handler.js';
+import { PATTERNS, BRANCHES, STRING_LITERALS, EXIT_CODES, } from '@lumenflow/core/lib/wu-constants.js';
+function run(cmd) {
+    try {
+        return execSync(cmd, { stdio: 'pipe', encoding: 'utf-8' }).trim();
+    }
+    catch {
+        return '';
+    }
+}
+function formatWUId(wuId) {
+    if (!wuId || typeof wuId !== 'string') {
+        throw createError(ErrorCodes.VALIDATION_ERROR, 'verifyWUComplete requires a WU id (e.g., WU-123)', { wuId, type: typeof wuId });
+    }
+    const normalized = wuId.trim().toUpperCase();
+    if (!PATTERNS.WU_ID.test(normalized)) {
+        throw createError(ErrorCodes.INVALID_WU_ID, `Invalid WU id "${wuId}". Expected format: WU-123`, { wuId, normalized });
+    }
+    return normalized;
+}
+function checkGitStatus(runFn = run) {
+    const status = runFn('git status --porcelain');
+    if (!status)
+        return null;
+    const lines = status.split(STRING_LITERALS.NEWLINE).filter(Boolean).slice(0, 10);
+    return `Working tree dirty (stage or discard changes): ${lines.join('; ')}`;
+}
+function stampPath(wuId) {
+    return path.join('.beacon', 'stamps', `${wuId}.done`);
+}
+function checkStamp(wuId, existsFn = existsSync) {
+    if (existsFn(stampPath(wuId)))
+        return null;
+    return `Missing stamp .beacon/stamps/${wuId}.done`;
+}
+function checkCommit(wuId, runFn = run) {
+    const history = runFn(`git log --oneline ${BRANCHES.MAIN} -- docs/04-operations/tasks/wu/${wuId}.yaml | head -n 1`);
+    if (history)
+        return null;
+    return `No commit on ${BRANCHES.MAIN} touching docs/04-operations/tasks/wu/${wuId}.yaml`;
+}
+/**
+ * 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 function verifyWUComplete(wuId, overrides = {}) {
+    const normalized = formatWUId(wuId);
+    const failures = [];
+    const runFn = typeof overrides.run === 'function' ? overrides.run : run;
+    const existsFn = typeof overrides.exists === 'function'
+        ? overrides.exists
+        : (filePath) => existsSync(filePath);
+    const gitStatusFailure = checkGitStatus(runFn);
+    if (gitStatusFailure)
+        failures.push(gitStatusFailure);
+    const stampFailure = checkStamp(normalized, existsFn);
+    if (stampFailure)
+        failures.push(stampFailure);
+    const commitFailure = checkCommit(normalized, runFn);
+    if (commitFailure)
+        failures.push(commitFailure);
+    return {
+        complete: failures.length === 0,
+        failures,
+    };
+}
+export function debugSummary(result) {
+    if (!result || typeof result !== 'object') {
+        return 'No verification result';
+    }
+    if (result.complete) {
+        return 'Verification passed: WU complete.';
+    }
+    const failures = Array.isArray(result.failures) ? result.failures : [];
+    if (!failures.length) {
+        return 'Verification failed: unknown reason.';
+    }
+    return `Verification failed:${STRING_LITERALS.NEWLINE}- ${failures.join(`${STRING_LITERALS.NEWLINE}- `)}`;
+}
+const isDirectExecution = (() => {
+    if (typeof process === 'undefined')
+        return false;
+    if (!Array.isArray(process.argv))
+        return false;
+    if (!process.argv[1])
+        return false;
+    try {
+        return fileURLToPath(import.meta.url) === process.argv[1];
+    }
+    catch {
+        return false;
+    }
+})();
+if (isDirectExecution) {
+    const wuId = process.argv[2];
+    try {
+        const result = verifyWUComplete(wuId);
+        const message = debugSummary(result);
+        console.log(message);
+        process.exit(result.complete ? EXIT_CODES.SUCCESS : EXIT_CODES.ERROR);
+    }
+    catch (error) {
+        console.error(`Verification error: ${error.message}`);
+        process.exit(EXIT_CODES.ERROR);
+    }
+}

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/auto-session-integration.js

@@ -0,0 +1,173 @@
+/**
+ * Auto-Session Integration for wu:claim and wu:done lifecycle (WU-1438, WU-1466)
+ *
+ * Provides wrapper functions around agent-session.mjs that:
+ * 1. Auto-start sessions on wu:claim with silent no-op if already active
+ * 2. Auto-end sessions on wu:done with silent no-op if not active
+ * 3. Store session_id in WU YAML for tracking
+ * 4. Create memory layer session nodes for context restoration (WU-1466)
+ *
+ * Design principles:
+ * - Composition over modification (wraps existing agent-session.mjs)
+ * - Silent failures for idempotent operations (no throw on duplicate start/end)
+ * - Configurable session directory for testing
+ */
+import { randomUUID } from 'crypto';
+import { readFileSync, writeFileSync, existsSync, unlinkSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { startSession as startMemorySession } from '@lumenflow/memory/start';
+// Default session directory (same as agent-session.mjs)
+const DEFAULT_SESSION_DIR = '.beacon/sessions';
+const SESSION_FILENAME = 'current.json';
+// Default context tier for auto-started sessions
+const DEFAULT_TIER = 2;
+// Agent type for auto-started sessions
+const DEFAULT_AGENT_TYPE = 'claude-code';
+/**
+ * Map numeric tier values to string names for memory layer (WU-1466)
+ */
+const CONTEXT_TIER_MAP = {
+    1: 'minimal',
+    2: 'core',
+    3: 'full',
+};
+/**
+ * Get the session file path for a given session directory
+ * @param sessionDir - Session directory path
+ * @returns Full path to current.json
+ */
+function getSessionFilePath(sessionDir) {
+    return join(sessionDir, SESSION_FILENAME);
+}
+/**
+ * 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 async function startSessionForWU(options) {
+    const { wuId, tier = DEFAULT_TIER, agentType = DEFAULT_AGENT_TYPE, sessionDir, baseDir = process.cwd(), } = options;
+    const sessDir = sessionDir ?? DEFAULT_SESSION_DIR;
+    const sessionFile = getSessionFilePath(sessDir);
+    // Check for existing session - return it instead of throwing
+    if (existsSync(sessionFile)) {
+        const existing = JSON.parse(readFileSync(sessionFile, { encoding: 'utf-8' }));
+        return {
+            sessionId: existing.session_id,
+            alreadyActive: true,
+        };
+    }
+    // Create session directory if needed
+    if (!existsSync(sessDir)) {
+        mkdirSync(sessDir, { recursive: true });
+    }
+    // Create new session
+    const sessionId = randomUUID();
+    const session = {
+        session_id: sessionId,
+        wu_id: wuId,
+        started: new Date().toISOString(),
+        agent_type: agentType,
+        context_tier: tier,
+        incidents_logged: 0,
+        incidents_major: 0,
+        auto_started: true, // Mark as auto-started by wu:claim
+    };
+    writeFileSync(sessionFile, JSON.stringify(session, null, 2), { encoding: 'utf-8' });
+    // WU-1466: Create memory layer session node for context restoration
+    // This enables context restoration after /clear by persisting session info to memory.jsonl
+    let memoryNodeId = null;
+    try {
+        const memResult = await startMemorySession(baseDir, {
+            wuId,
+            agentType,
+            contextTier: CONTEXT_TIER_MAP[tier] ?? 'full',
+        });
+        memoryNodeId = memResult.session?.id ?? null;
+    }
+    catch {
+        // Memory layer creation is non-blocking - log but don't fail
+        // Session file was already created, so the session is functional
+    }
+    return {
+        sessionId,
+        alreadyActive: false,
+        memoryNodeId,
+    };
+}
+/**
+ * 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 function endSessionForWU(options = {}) {
+    const { sessionDir } = options;
+    const sessDir = sessionDir ?? DEFAULT_SESSION_DIR;
+    const sessionFile = getSessionFilePath(sessDir);
+    // Check for active session - return early if none
+    if (!existsSync(sessionFile)) {
+        return {
+            ended: false,
+            reason: 'no_active_session',
+        };
+    }
+    // Read session data
+    const session = JSON.parse(readFileSync(sessionFile, { encoding: 'utf-8' }));
+    // Finalize session
+    session.completed = new Date().toISOString();
+    // Build summary for WU YAML
+    const summary = {
+        wu_id: session.wu_id,
+        session_id: session.session_id,
+        started: session.started,
+        completed: session.completed,
+        agent_type: session.agent_type,
+        context_tier: session.context_tier,
+        incidents_logged: session.incidents_logged,
+        incidents_major: session.incidents_major,
+    };
+    // Remove session file
+    unlinkSync(sessionFile);
+    return {
+        ended: true,
+        summary,
+    };
+}
+/**
+ * Get the current active session
+ *
+ * @param options - Session options
+ * @returns Session object or null if no active session
+ */
+export function getCurrentSessionForWU(options = {}) {
+    const { sessionDir } = options;
+    const sessDir = sessionDir ?? DEFAULT_SESSION_DIR;
+    const sessionFile = getSessionFilePath(sessDir);
+    if (!existsSync(sessionFile)) {
+        return null;
+    }
+    return JSON.parse(readFileSync(sessionFile, { encoding: 'utf-8' }));
+}
+/**
+ * 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 function hasActiveSessionForWU(wuId, options = {}) {
+    const session = getCurrentSessionForWU(options);
+    return session !== null && session.wu_id === wuId;
+}