@kynetic-ai/spec 0.4.0 → 0.6.0

package/dist/sessions/store.js

@@ -15,11 +15,12 @@ import * as fs from "node:fs";
 import * as fsPromises from "node:fs/promises";
 import * as path from "node:path";
 import * as YAML from "yaml";
-import { SessionEventSchema, SessionMetadataSchema, } from "./types.js";
+import { SessionEventSchema, SessionMetadataSchema, TaskBudgetSchema, } from "./types.js";
 // ─── Constants ───────────────────────────────────────────────────────────────
 const SESSIONS_DIR = "sessions";
 const METADATA_FILE = "session.yaml";
 const EVENTS_FILE = "events.jsonl";
+const BUDGET_FILE = "budget.json";
 // ─── Path Helpers ────────────────────────────────────────────────────────────
 /**
  * Get the sessions directory path within a spec directory.
@@ -51,6 +52,13 @@ export function getSessionEventsPath(specDir, sessionId) {
 export function getSessionContextPath(specDir, sessionId, iteration) {
     return path.join(getSessionDir(specDir, sessionId), `context-iter-${iteration}.json`);
 }
+/**
+ * Get the path to a session's budget file.
+ * AC: @session-creation-and-env-injection ac-budget-local
+ */
+export function getSessionBudgetPath(specDir, sessionId) {
+    return path.join(getSessionDir(specDir, sessionId), BUDGET_FILE);
+}
 // ─── Session CRUD ────────────────────────────────────────────────────────────
 /**
  * Create a new session with metadata.
@@ -165,6 +173,97 @@ export async function sessionExists(specDir, sessionId) {
         return false;
     }
 }
+// ─── End-Loop Signal ────────────────────────────────────────────────────────
+/**
+ * Request end-loop for a session.
+ *
+ * Writes end_requested=true and optional end_reason to the session metadata.
+ * This is the session-scoped replacement for the marker file approach.
+ *
+ * AC: @session-end-loop-signal ac-signal
+ *
+ * @param specDir - The .kspec directory path
+ * @param sessionId - Session ID
+ * @param reason - Optional reason for ending the loop
+ * @returns Updated metadata or null if session not found
+ */
+export async function requestEndLoop(specDir, sessionId, reason) {
+    const metadata = await getSession(specDir, sessionId);
+    if (!metadata) {
+        return null;
+    }
+    const updated = {
+        ...metadata,
+        end_requested: true,
+        end_reason: reason,
+    };
+    const metadataPath = getSessionMetadataPath(specDir, sessionId);
+    const content = YAML.stringify(updated, {
+        indent: 2,
+        lineWidth: 100,
+        sortMapEntries: false,
+    });
+    await fsPromises.writeFile(metadataPath, content, "utf-8");
+    return updated;
+}
+/**
+ * Check if end-loop has been requested for a session.
+ *
+ * Only returns requested=true for active sessions. If the session is
+ * completed or abandoned, the end-loop signal is no longer relevant
+ * (prevents stale KSPEC_SESSION_ID from blocking task starts).
+ *
+ * AC: @session-end-loop-signal ac-detect
+ *
+ * @param specDir - The .kspec directory path
+ * @param sessionId - Session ID
+ * @returns Object with requested flag and optional reason, or null if session not found
+ */
+export async function isEndLoopRequested(specDir, sessionId) {
+    const metadata = await getSession(specDir, sessionId);
+    if (!metadata) {
+        return null;
+    }
+    return {
+        requested: metadata.end_requested === true && metadata.status === "active",
+        reason: metadata.end_reason,
+    };
+}
+/**
+ * Close a session with a specific status and reason.
+ *
+ * Used for all session close paths: normal exit, signal, error.
+ *
+ * AC: @session-end-loop-signal ac-session-close-normal
+ * AC: @session-end-loop-signal ac-session-close-signal
+ * AC: @session-end-loop-signal ac-session-close-error
+ *
+ * @param specDir - The .kspec directory path
+ * @param sessionId - Session ID
+ * @param status - New status (completed or abandoned)
+ * @param reason - Reason for closing
+ * @returns Updated metadata or null if session not found
+ */
+export async function closeSession(specDir, sessionId, status, reason) {
+    const metadata = await getSession(specDir, sessionId);
+    if (!metadata) {
+        return null;
+    }
+    const updated = {
+        ...metadata,
+        status,
+        ended_at: new Date().toISOString(),
+        close_reason: reason,
+    };
+    const metadataPath = getSessionMetadataPath(specDir, sessionId);
+    const content = YAML.stringify(updated, {
+        indent: 2,
+        lineWidth: 100,
+        sortMapEntries: false,
+    });
+    await fsPromises.writeFile(metadataPath, content, "utf-8");
+    return updated;
+}
 // ─── Event Storage ───────────────────────────────────────────────────────────
 /**
  * Get the current event count for a session (for seq assignment).
@@ -1101,4 +1200,525 @@ export async function searchSessionEvents(specDir, pattern, options = {}) {
     }
     return results;
 }
+// ─── Session Creation with Budget ─────────────────────────────────────────────
+/**
+ * Create a session with an optional task budget in one call.
+ *
+ * This is the library-level entry point for session creation. It creates
+ * the session directory, writes session.yaml, and optionally writes budget.json.
+ * Returns metadata without any console output.
+ *
+ * AC: @session-creation-and-env-injection ac-create
+ * AC: @session-creation-and-env-injection ac-budget
+ * AC: @session-creation-and-env-injection ac-budget-local
+ * AC: @session-creation-and-env-injection ac-library
+ *
+ * @param specDir - The .kspec directory path
+ * @param input - Session creation parameters
+ * @returns Session metadata and optional budget (no console output)
+ */
+export async function createSessionWithBudget(specDir, input) {
+    // Create session
+    const session = await createSession(specDir, {
+        id: input.id,
+        agent_type: input.agent_type,
+        task_id: input.task_id,
+    });
+    // Optionally create budget
+    let budget = null;
+    if (input.budget !== undefined && input.budget > 0) {
+        budget = await createBudget(specDir, input.id, input.budget);
+    }
+    return {
+        session_id: input.id,
+        session,
+        budget,
+    };
+}
+/**
+ * Write or update KSPEC_SESSION_ID in a dotenv-style file.
+ * Replaces an existing KSPEC_SESSION_ID line or appends a new one.
+ */
+async function upsertDotenvSessionId(filePath, sessionId) {
+    let content = "";
+    try {
+        content = await fsPromises.readFile(filePath, "utf-8");
+    }
+    catch (err) {
+        if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+            // File doesn't exist yet, start fresh
+        }
+        else {
+            throw err;
+        }
+    }
+    const lines = content.split("\n");
+    const existingIdx = lines.findIndex((l) => l.startsWith("KSPEC_SESSION_ID="));
+    if (existingIdx >= 0) {
+        lines[existingIdx] = `KSPEC_SESSION_ID=${sessionId}`;
+    }
+    else {
+        // Append before final empty line if present
+        if (lines.length > 0 && lines[lines.length - 1] === "") {
+            lines.splice(lines.length - 1, 0, `KSPEC_SESSION_ID=${sessionId}`);
+        }
+        else {
+            lines.push(`KSPEC_SESSION_ID=${sessionId}`);
+        }
+    }
+    await fsPromises.writeFile(filePath, lines.join("\n"), "utf-8");
+}
+/**
+ * Inject KSPEC_SESSION_ID into Claude Code environment.
+ *
+ * Strategy:
+ * 1. If CLAUDE_ENV_FILE is set, write to that file
+ * 2. Otherwise, append to project .claude/settings.local.json env section
+ *
+ * AC: @session-creation-and-env-injection ac-inject-claude
+ */
+export async function injectClaudeCodeEnv(sessionId) {
+    const envFile = process.env.CLAUDE_ENV_FILE;
+    if (envFile) {
+        const previousValue = await readDotenvSessionId(envFile);
+        await upsertDotenvSessionId(envFile, sessionId);
+        return {
+            injected: true,
+            method: "claude_env_file",
+            description: `Wrote KSPEC_SESSION_ID=${sessionId} to CLAUDE_ENV_FILE`,
+            path: envFile,
+            previousValue,
+        };
+    }
+    // Fallback: write to project .claude/settings.local.json (gitignored, user-local)
+    // Using settings.local.json avoids dirtying the working tree — settings.json
+    // is checked into the repo. Claude Code merges both, with local taking precedence.
+    const settingsDir = path.join(process.cwd(), ".claude");
+    const settingsPath = path.join(settingsDir, "settings.local.json");
+    await fsPromises.mkdir(settingsDir, { recursive: true });
+    let settings = {};
+    try {
+        const content = await fsPromises.readFile(settingsPath, "utf-8");
+        settings = JSON.parse(content);
+    }
+    catch (err) {
+        // Only start fresh for ENOENT; throw on parse errors to avoid overwriting
+        if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+            // File doesn't exist, start fresh
+        }
+        else {
+            throw new Error(`Cannot inject env: .claude/settings.local.json exists but is not valid JSON. ` +
+                `Fix the file manually or remove it, then retry.`);
+        }
+    }
+    // Capture previous value before overwriting
+    const previousValue = settings.env && typeof settings.env === "object"
+        ? (settings.env.KSPEC_SESSION_ID ?? null)
+        : null;
+    // Ensure env section exists
+    if (!settings.env || typeof settings.env !== "object") {
+        settings.env = {};
+    }
+    settings.env.KSPEC_SESSION_ID = sessionId;
+    await fsPromises.writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+    return {
+        injected: true,
+        method: "claude_settings",
+        description: `Added KSPEC_SESSION_ID to .claude/settings.local.json env section`,
+        path: settingsPath,
+        previousValue,
+    };
+}
+/**
+ * Remove or restore KSPEC_SESSION_ID in Claude Code environment.
+ *
+ * Reverses the injection performed by injectClaudeCodeEnv().
+ * If previousValue is provided, restores it instead of deleting.
+ * Best-effort: silently ignores missing files or missing keys.
+ *
+ * @param previousValue - Value to restore, or null/undefined to delete
+ */
+export async function removeClaudeCodeEnv(previousValue) {
+    const envFile = process.env.CLAUDE_ENV_FILE;
+    if (envFile) {
+        if (previousValue) {
+            await upsertDotenvSessionId(envFile, previousValue);
+        }
+        else {
+            await removeDotenvSessionId(envFile);
+        }
+        return;
+    }
+    // Remove/restore in project .claude/settings.local.json
+    const settingsPath = path.join(process.cwd(), ".claude", "settings.local.json");
+    try {
+        const content = await fsPromises.readFile(settingsPath, "utf-8");
+        const settings = JSON.parse(content);
+        if (settings.env && typeof settings.env === "object") {
+            if (previousValue) {
+                settings.env.KSPEC_SESSION_ID = previousValue;
+            }
+            else {
+                delete settings.env.KSPEC_SESSION_ID;
+                // Remove env section entirely if empty
+                if (Object.keys(settings.env).length === 0) {
+                    delete settings.env;
+                }
+            }
+            await fsPromises.writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+        }
+    }
+    catch {
+        // Best-effort cleanup — file may not exist or may not be valid JSON
+    }
+}
+/**
+ * Read existing KSPEC_SESSION_ID from a dotenv-style file.
+ * Returns the value or null if not found.
+ */
+async function readDotenvSessionId(filePath) {
+    try {
+        const content = await fsPromises.readFile(filePath, "utf-8");
+        const match = content.match(/^KSPEC_SESSION_ID=(.+)$/m);
+        return match ? match[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Remove KSPEC_SESSION_ID line from a dotenv-style file.
+ */
+async function removeDotenvSessionId(filePath) {
+    try {
+        const content = await fsPromises.readFile(filePath, "utf-8");
+        const lines = content.split("\n");
+        const filtered = lines.filter((l) => !l.startsWith("KSPEC_SESSION_ID="));
+        if (filtered.length !== lines.length) {
+            await fsPromises.writeFile(filePath, filtered.join("\n"), "utf-8");
+        }
+    }
+    catch {
+        // Best-effort cleanup
+    }
+}
+/**
+ * Inject KSPEC_SESSION_ID into Codex CLI environment.
+ *
+ * Adds to shell_environment_policy.set in codex config.
+ *
+ * AC: @session-creation-and-env-injection ac-inject-codex
+ */
+export async function injectCodexEnv(sessionId) {
+    const configDir = path.join(process.env.HOME || process.env.USERPROFILE || "", ".codex");
+    const configPath = path.join(configDir, "config.json");
+    await fsPromises.mkdir(configDir, { recursive: true });
+    let config = {};
+    try {
+        const content = await fsPromises.readFile(configPath, "utf-8");
+        config = JSON.parse(content);
+    }
+    catch (err) {
+        // Only start fresh for ENOENT; throw on parse errors to avoid overwriting
+        if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+            // File doesn't exist, start fresh
+        }
+        else {
+            throw new Error(`Cannot inject env: ~/.codex/config.json exists but is not valid JSON. ` +
+                `Fix the file manually or remove it, then retry.`);
+        }
+    }
+    // Ensure shell_environment_policy.set exists
+    if (!config.shell_environment_policy ||
+        typeof config.shell_environment_policy !== "object") {
+        config.shell_environment_policy = {};
+    }
+    const policy = config.shell_environment_policy;
+    if (!policy.set || typeof policy.set !== "object") {
+        policy.set = {};
+    }
+    policy.set.KSPEC_SESSION_ID = sessionId;
+    await fsPromises.writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+    return {
+        injected: true,
+        method: "codex_config",
+        description: `Added KSPEC_SESSION_ID to Codex config shell_environment_policy.set`,
+        path: configPath,
+    };
+}
+/**
+ * Inject KSPEC_SESSION_ID into Gemini CLI environment.
+ *
+ * Writes to .gemini/.env in project root (auto-loaded by Gemini CLI).
+ */
+export async function injectGeminiEnv(sessionId) {
+    const dotenvDir = path.join(process.cwd(), ".gemini");
+    const dotenvPath = path.join(dotenvDir, ".env");
+    await fsPromises.mkdir(dotenvDir, { recursive: true });
+    await upsertDotenvSessionId(dotenvPath, sessionId);
+    return {
+        injected: true,
+        method: "gemini_dotenv",
+        description: `Wrote KSPEC_SESSION_ID=${sessionId} to .gemini/.env`,
+        path: dotenvPath,
+    };
+}
+/**
+ * Inject KSPEC_SESSION_ID into OpenCode environment.
+ *
+ * Writes to project root .env file (auto-loaded by OpenCode via Bun runtime).
+ * Uses the same dotenv append/replace pattern as other injectors.
+ */
+export async function injectOpenCodeEnv(sessionId) {
+    const dotenvPath = path.join(process.cwd(), ".env");
+    await upsertDotenvSessionId(dotenvPath, sessionId);
+    return {
+        injected: true,
+        method: "opencode_dotenv",
+        description: `Wrote KSPEC_SESSION_ID=${sessionId} to .env`,
+        path: dotenvPath,
+    };
+}
+/**
+ * Get fallback injection instructions for unknown agent harnesses.
+ *
+ * AC: @session-creation-and-env-injection ac-inject-fallback
+ */
+export function getFallbackInjectionInstructions(sessionId) {
+    return {
+        injected: false,
+        method: "fallback",
+        description: `export KSPEC_SESSION_ID=${sessionId}`,
+    };
+}
+// ─── Adapter-based Env Injection ──────────────────────────────────────────────
+/**
+ * Inject KSPEC_SESSION_ID via the appropriate mechanism for the given adapter.
+ *
+ * Ralph passes env vars to spawned agents via process environment, but some
+ * harnesses (Claude Code, Codex, etc.) sandbox child processes and don't
+ * forward arbitrary parent env vars. This function writes the session ID to
+ * the harness-specific config location so it reaches kspec subprocesses.
+ *
+ * @param adapterId - The adapter identifier (e.g., "claude-agent-acp")
+ * @param sessionId - The session ID to inject
+ * @returns Injection result, or null if no harness-specific injection is needed
+ */
+export async function injectEnvForAdapter(adapterId, sessionId) {
+    switch (adapterId) {
+        case "claude-agent-acp":
+        case "claude-code-acp":
+            return injectClaudeCodeEnv(sessionId);
+        // Future harnesses can be added here:
+        // case "codex-acp":
+        //   return injectCodexEnv(sessionId);
+        // case "gemini-acp":
+        //   return injectGeminiEnv(sessionId);
+        default:
+            return null; // Unknown adapter — rely on process env inheritance
+    }
+}
+/**
+ * Remove KSPEC_SESSION_ID from the harness config for the given adapter.
+ *
+ * Reverses the injection performed by injectEnvForAdapter().
+ * If previousValue is provided, restores it instead of deleting.
+ * Best-effort: silently ignores errors.
+ *
+ * @param adapterId - The adapter identifier
+ * @param previousValue - Value to restore, or null/undefined to delete
+ */
+export async function removeEnvForAdapter(adapterId, previousValue) {
+    switch (adapterId) {
+        case "claude-agent-acp":
+        case "claude-code-acp":
+            await removeClaudeCodeEnv(previousValue);
+            break;
+        // Future harnesses can be added here
+    }
+}
+// ─── Session Validation ───────────────────────────────────────────────────────
+/**
+ * Validate that the current KSPEC_SESSION_ID points to a valid session.
+ *
+ * AC: @session-creation-and-env-injection ac-invalid-session
+ *
+ * @param specDir - The .kspec directory path
+ * @param sessionId - The session ID to validate
+ * @returns Validation result with error details if invalid
+ */
+export async function validateSessionId(specDir, sessionId) {
+    // Check if session directory exists
+    const exists = await sessionExists(specDir, sessionId);
+    if (!exists) {
+        return {
+            valid: false,
+            error: `Session not found: ${sessionId}`,
+            suggestion: `Unset KSPEC_SESSION_ID or create a new session with: kspec session create --agent-type <type>`,
+        };
+    }
+    // Try to read and validate session metadata
+    const session = await getSession(specDir, sessionId);
+    if (!session) {
+        return {
+            valid: false,
+            error: `Session metadata is corrupt or unreadable: ${sessionId}`,
+            suggestion: `Unset KSPEC_SESSION_ID or create a new session with: kspec session create --agent-type <type>`,
+        };
+    }
+    return { valid: true, session };
+}
+// ─── Task Budget ──────────────────────────────────────────────────────────────
+/**
+ * Atomic JSON write — write to temp file then rename in same directory.
+ * Prevents corruption on crash.
+ * AC: @task-budget-enforcement ac-atomic-write
+ */
+async function writeBudgetAtomic(filePath, budget) {
+    const dir = path.dirname(filePath);
+    await fsPromises.mkdir(dir, { recursive: true });
+    const tmpPath = `${filePath}.${process.pid}.tmp`;
+    const content = JSON.stringify(budget, null, 2) + "\n";
+    await fsPromises.writeFile(tmpPath, content, "utf-8");
+    await fsPromises.rename(tmpPath, filePath);
+}
+/**
+ * Create a budget for a session.
+ *
+ * Writes budget.json to .kspec/sessions/{id}/ on the local filesystem
+ * (NOT committed to shadow branch).
+ *
+ * AC: @session-creation-and-env-injection ac-budget
+ * AC: @session-creation-and-env-injection ac-budget-local
+ *
+ * @param specDir - The .kspec directory path
+ * @param sessionId - Session ID
+ * @param maxPerCycle - Maximum tasks allowed per cycle
+ * @returns The created budget
+ */
+export async function createBudget(specDir, sessionId, maxPerCycle) {
+    const budget = {
+        max_per_cycle: maxPerCycle,
+        started_this_cycle: 0,
+    };
+    const validated = TaskBudgetSchema.parse(budget);
+    const budgetPath = getSessionBudgetPath(specDir, sessionId);
+    await writeBudgetAtomic(budgetPath, validated);
+    return validated;
+}
+/**
+ * Read budget for a session.
+ *
+ * AC: @task-budget-enforcement ac-no-budget
+ *
+ * @param specDir - The .kspec directory path
+ * @param sessionId - Session ID
+ * @returns Budget or null if no budget configured (opt-in)
+ */
+export async function getBudget(specDir, sessionId) {
+    const budgetPath = getSessionBudgetPath(specDir, sessionId);
+    let content;
+    try {
+        content = await fsPromises.readFile(budgetPath, "utf-8");
+    }
+    catch (err) {
+        // File doesn't exist = no budget configured (opt-in)
+        if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+            return null;
+        }
+        throw err;
+    }
+    // File exists — parse errors are real failures, not "no budget"
+    const raw = JSON.parse(content);
+    return TaskBudgetSchema.parse(raw);
+}
+/**
+ * Check whether the budget allows starting a new task.
+ *
+ * Returns an object with `allowed` boolean and context about the budget.
+ * When no budget is configured, always allows (opt-in behavior).
+ *
+ * AC: @task-budget-enforcement ac-block-start
+ * AC: @task-budget-enforcement ac-no-budget
+ * AC: @task-budget-enforcement ac-no-session
+ *
+ * @param specDir - The .kspec directory path
+ * @param sessionId - Session ID, or undefined if KSPEC_SESSION_ID not set
+ * @returns Budget check result
+ */
+export async function checkBudget(specDir, sessionId) {
+    // AC: @task-budget-enforcement ac-no-session — no session means no check
+    if (!sessionId) {
+        return { allowed: true };
+    }
+    const budget = await getBudget(specDir, sessionId);
+    // AC: @task-budget-enforcement ac-no-budget — no budget means no check
+    if (!budget) {
+        return { allowed: true };
+    }
+    if (budget.started_this_cycle >= budget.max_per_cycle) {
+        return {
+            allowed: false,
+            reason: `Task budget exhausted: ${budget.started_this_cycle}/${budget.max_per_cycle} tasks started this cycle. Wrap up current work and let the iteration end naturally without starting new tasks.`,
+            budget,
+        };
+    }
+    return { allowed: true, budget };
+}
+/**
+ * Increment the budget counter after a task is successfully started.
+ *
+ * IMPORTANT: Callers must NOT call this for resume cases (task already
+ * in_progress). The budget should only be incremented when a new task
+ * transitions to in_progress, not when resuming an existing one.
+ * See AC: @task-budget-enforcement ac-resume-no-increment
+ *
+ * AC: @task-budget-enforcement ac-increment
+ * AC: @task-budget-enforcement ac-atomic-write
+ *
+ * @param specDir - The .kspec directory path
+ * @param sessionId - Session ID
+ * @returns Updated budget, or null if no budget configured
+ */
+export async function incrementBudget(specDir, sessionId) {
+    const budget = await getBudget(specDir, sessionId);
+    if (!budget) {
+        return null;
+    }
+    const updated = {
+        ...budget,
+        started_this_cycle: budget.started_this_cycle + 1,
+    };
+    const validated = TaskBudgetSchema.parse(updated);
+    const budgetPath = getSessionBudgetPath(specDir, sessionId);
+    await writeBudgetAtomic(budgetPath, validated);
+    return validated;
+}
+/**
+ * Reset the budget counter to 0 for a new cycle/iteration.
+ *
+ * Called by ralph at iteration boundaries. Single-writer guarantee:
+ * ralph only resets between iterations when the agent is not running.
+ *
+ * AC: @task-budget-enforcement ac-reset
+ * AC: @task-budget-enforcement ac-atomic-write
+ *
+ * @param specDir - The .kspec directory path
+ * @param sessionId - Session ID
+ * @returns Updated budget, or null if no budget configured
+ */
+export async function resetBudget(specDir, sessionId) {
+    const budget = await getBudget(specDir, sessionId);
+    if (!budget) {
+        return null;
+    }
+    const updated = {
+        ...budget,
+        started_this_cycle: 0,
+    };
+    const validated = TaskBudgetSchema.parse(updated);
+    const budgetPath = getSessionBudgetPath(specDir, sessionId);
+    await writeBudgetAtomic(budgetPath, validated);
+    return validated;
+}
 //# sourceMappingURL=store.js.map