agent-enderun 1.1.9 → 1.10.0

package/src/cli/utils/memory.ts

@@ -1,11 +1,13 @@
 import fs from "fs";
 import os from "os";
 import path from "path";
-import { sleep } from "./time.js";
-import { generateULID } from "./time.js";
-import { FRAMEWORK_DIR_CANDIDATES } from "../adapters.js";
-import { EnderunConfigSchema } from "./config-schema.js";
 import { logger } from "../../shared/logger.js";
+import { ensureDir, writeTextFile, writeJsonFile } from "../../shared/fs.js";
+import { StateSchema, AgentStatusSchema, TaskSchema } from "./schemas.js";
+import type { TraceID } from "../../shared/types.js";
+
+export { generateULID } from "./time.js";
+export { FRAMEWORK_DIR_CANDIDATES } from "../adapters/index.js";
 
 const CWD = process.cwd();
 const HOME = os.homedir();
@@ -23,16 +25,6 @@ function findFrameworkDir(basePath: string): string | null {
     } catch (err) {
         logger.debug("Failed to read package.json in findFrameworkDir", err);
     }
-
-    for (const dir of FRAMEWORK_DIR_CANDIDATES) {
-        const dirPath = path.join(basePath, dir);
-        if (fs.existsSync(dirPath) && fs.lstatSync(dirPath).isDirectory()) {
-            const hasMemory = fs.existsSync(path.join(dirPath, "PROJECT_MEMORY.md")) ||
-                              fs.existsSync(path.join(dirPath, "memory/PROJECT_MEMORY.md")) ||
-                              fs.existsSync(path.join(dirPath, "config.json"));
-            if (hasMemory) return dirPath;
-        }
-    }
     return null;
 }
 
@@ -44,179 +36,232 @@ export function getLocalFrameworkDir(): string {
 export function getConfigDir(): string {
     const localDir = findFrameworkDir(CWD);
     if (localDir) return localDir;
-    const globalDir = findFrameworkDir(HOME);
-    return globalDir || path.join(HOME, ".gemini");
+
+    // Check for standard local directories if package.json doesn't specify
+    const localCandidates = [".enderun", ".gemini", ".claude", ".cursor", ".antigravity", ".agent"];
+    for (const cand of localCandidates) {
+        const p = path.join(CWD, cand);
+        if (fs.existsSync(p)) return p;
+    }
+
+    return path.join(HOME, ".gemini");
 }
 
 export function getFrameworkDir(): string {
+    if (process.env.ENDERUN_TEST_DIR) return process.env.ENDERUN_TEST_DIR;
     return getConfigDir();
 }
 
-export function getMemoryPath() {
-    const frameworkDir = getLocalFrameworkDir();
-    const subPath = path.join(frameworkDir, "memory/PROJECT_MEMORY.md");
-    if (fs.existsSync(subPath)) return subPath;
-    return path.join(frameworkDir, "PROJECT_MEMORY.md");
+export function getDocumentStorePath() {
+    const frameworkDir = getFrameworkDir();
+    return path.join(frameworkDir, "memory");
+}
+
+export function initDocumentStore(frameworkDir?: string) {
+    const storePath = frameworkDir ? path.join(frameworkDir, "memory") : getDocumentStorePath();
+    ensureDir(storePath);
+    ensureDir(path.join(storePath, "tasks"));
+    ensureDir(path.join(storePath, "history"));
+    
+    const stateFile = path.join(storePath, "state.json");
+    if (!fs.existsSync(stateFile)) {
+        writeJsonFile(stateFile, { phase: "PHASE_0", traceId: "T-000", managerState: "ACTIVE" });
+    }
+    const statusFile = path.join(storePath, "status.json");
+    if (!fs.existsSync(statusFile)) {
+        writeJsonFile(statusFile, {});
+    }
+
+    // Ensure the initial Markdown view is created
+    syncMarkdownMemory(frameworkDir);
+}
+
+export function readState() {
+    const statePath = path.join(getDocumentStorePath(), "state.json");
+    if (!fs.existsSync(statePath)) return null;
+    return JSON.parse(fs.readFileSync(statePath, "utf8"));
+}
+
+export function readStatus() {
+    const statusPath = path.join(getDocumentStorePath(), "status.json");
+    if (!fs.existsSync(statusPath)) return {};
+    return JSON.parse(fs.readFileSync(statusPath, "utf8"));
+}
+
+export function listTasks() {
+    const tasksPath = path.join(getDocumentStorePath(), "tasks");
+    if (!fs.existsSync(tasksPath)) return [];
+    
+    return fs.readdirSync(tasksPath)
+        .filter(f => f.endsWith(".json"))
+        .map(f => JSON.parse(fs.readFileSync(path.join(tasksPath, f), "utf8")));
+}
+
+export function getMemoryPath(): string {
+    return path.join(getDocumentStorePath(), "state.json");
 }
 
-export function getConfiguredPaths(): { backend: string; frontend: string; docs: string; tests: string } {
-    const defaultPaths = { backend: "apps/backend", frontend: "apps/web", docs: "docs", tests: "tests" };
+export function readActiveTraceId(memoryContent: string): string | null {
+    try {
+        const state = JSON.parse(memoryContent);
+        return state.traceId || null;
+    } catch {
+        return null;
+    }
+}
+
+export function updateProjectMemory(section: string, content: string) {
+    if (section === "HISTORY") {
+        updateDocumentStore("history", { content }, new Date().toISOString().replace(/[:.]/g, "-"));
+    } else {
+        const state = readState() || {};
+        state[section] = content;
+        updateDocumentStore("state", state);
+    }
+}
+
+export function initializeMemory(memoryPathOrBase: string, targetBaseOrDryRun?: string | boolean): void {
+    const targetBase = typeof targetBaseOrDryRun === "string" ? targetBaseOrDryRun : memoryPathOrBase;
+    initDocumentStore(targetBase);
+    logger.info("✅ Document store initialized.");
+}
+
+export function getConfiguredPaths(): { backend: string; frontend: string; mobile: string; docs: string; tests: string } {
+    const defaultPaths = { backend: "apps/backend", frontend: "apps/web", mobile: "apps/mobile", docs: "docs", tests: "tests" };
     try {
         const frameworkDir = getConfigDir();
         const configPath = path.join(frameworkDir, "config.json");
         if (fs.existsSync(configPath)) {
             const rawConfig = JSON.parse(fs.readFileSync(configPath, "utf8"));
-            const result = EnderunConfigSchema.safeParse(rawConfig);
-            if (result.success) {
-                return result.data.paths;
-            } else {
-                console.error(`\n❌ Configuration Error in ${configPath}:`);
-                result.error.issues.forEach(err => console.error(`   - ${err.path.join(".")}: ${err.message}`));
-            }
+            return rawConfig.paths || defaultPaths;
         }
     } catch (err) {
-        console.error("\n❌ Critical Error: Could not read or parse configuration file.");
         logger.debug("Critical config read failure", err);
     }
     return defaultPaths;
 }
 
-export function acquireMemoryLock(lockPath: string, maxRetries = 5): boolean {
-    for (let attempt = 0; attempt < maxRetries; attempt += 1) {
-        try {
-            const fd = fs.openSync(lockPath, "wx");
-            fs.closeSync(fd);
-            return true;
-        } catch (error: unknown) {
-            const err = error as NodeJS.ErrnoException;
-            if (err?.code !== "EEXIST") throw error;
+export function updateDocumentStore(type: "state" | "task" | "history" | "status", data: unknown, id?: string | TraceID, frameworkDir?: string) {
+    const storePath = frameworkDir ? path.join(frameworkDir, "memory") : getDocumentStorePath();
+    ensureDir(storePath);
 
-            try {
-                if (fs.existsSync(lockPath)) {
-                    const stat = fs.statSync(lockPath);
-                    const ageMs = Date.now() - stat.mtimeMs;
-                    if (ageMs > 10000) { // 10 seconds timeout for memory writes
-                        console.warn(`\n⚠️  Stale memory lock detected (${Math.round(ageMs / 1000)}s old). Breaking lock: ${lockPath}`);
-                        fs.unlinkSync(lockPath);
-                        // Retry immediately
-                        const fd = fs.openSync(lockPath, "wx");
-                        fs.closeSync(fd);
-                        return true;
-                    }
-                }
-            } catch (err) {
-                logger.debug("Lock check or breaking failed", err);
-            }
-
-            if (attempt < maxRetries - 1) sleep(1000);
-        }
+    switch (type) {
+        case "state":
+            StateSchema.parse(data);
+            writeJsonFile(path.join(storePath, "state.json"), data);
+            break;
+        case "status":
+            AgentStatusSchema.parse(data);
+            writeJsonFile(path.join(storePath, "status.json"), data);
+            break;
+        case "task":
+            TaskSchema.parse(data);
+            ensureDir(path.join(storePath, "tasks"));
+            writeJsonFile(path.join(storePath, "tasks", `${id}.json`), data);
+            break;
+        case "history":
+            ensureDir(path.join(storePath, "history"));
+            writeJsonFile(path.join(storePath, "history", `${id}.json`), data);
+            break;
     }
-    return false;
-}
 
-export function releaseMemoryLock(lockPath: string): void {
-    if (fs.existsSync(lockPath)) fs.unlinkSync(lockPath);
+    // Auto-sync Markdown view after any change
+    syncMarkdownMemory(frameworkDir);
 }
 
-export function initializeMemory(memoryPath: string, targetBase: string, dryRun = false): void {
-    if (fs.existsSync(memoryPath)) return;
-    const traceId = generateULID();
-    const date = new Date().toISOString().split("T")[0];
-    const template = `## CURRENT STATUS\n\n- Phase: PHASE_0 (Genesis)\n- Trace ID: ${traceId}\n\n## HISTORY\n### ${date} — Initialization\n- Action: Initialized Enderun Core.\n`;
-    if (dryRun) return;
-    const parentDir = path.dirname(memoryPath);
-    if (!fs.existsSync(parentDir)) fs.mkdirSync(parentDir, { recursive: true });
-    fs.writeFileSync(memoryPath, template);
-    console.warn("✅ PROJECT_MEMORY.md initialized.");
-
-    const decisionsPath = path.join(parentDir, "DECISIONS.md");
-    if (!fs.existsSync(decisionsPath)) {
-        const decisionsTemplate = "# 🏛️ Architectural Decisions Log (ADR)\n\nThis file contains the fixed architectural choices and constraints for this project.\n\n## Decided Constraints\n- **Framework Integration:** Agent Enderun is the primary governance and orchestration layer.\n- **Language & Runtime:** TypeScript on Node.js.\n- **Package Manager:** npm.\n- **Monorepo Structure:** Monorepo using npm workspaces.\n- **Styling:** Panda CSS.\n";
-        fs.writeFileSync(decisionsPath, decisionsTemplate);
-        console.warn("✅ DECISIONS.md initialized.");
-    }
-}
+/**
+ * Single Source of Truth Bridge: JSON -> Markdown
+ * Regenerates PROJECT_MEMORY.md from structured state.
+ */
+export function syncMarkdownMemory(fDir?: string) {
+    const frameworkDir = fDir || getFrameworkDir();
+    const storePath = path.join(frameworkDir, "memory");
+    const mdPath = path.join(storePath, "PROJECT_MEMORY.md");
 
-export function updateProjectMemory(section: string, content: string) {
-    const memoryPath = getMemoryPath();
+    try {
+        const state = readState();
+        const status = readStatus();
+        const tasks = listTasks();
 
-    if (!fs.existsSync(memoryPath)) {
-        console.error("❌ Error: PROJECT_MEMORY.md not found.");
-        return;
-    }
+        if (!state) return;
 
-    const lockPath = `${memoryPath}.lock`;
-    if (!acquireMemoryLock(lockPath)) {
-        console.error("❌ Error: Memory lock timeout.");
-        return;
-    }
+        const lines = [
+            "# 🧠 Agent Enderun — Project Memory",
+            "",
+            "## 📍 Current State",
+            `- **Phase:** ${state.phase || "PHASE_0"}`,
+            `- **Trace ID:** ${state.traceId || "N/A"}`,
+            `- **@manager state:** ${state.managerState || "ACTIVE"}`,
+            "",
+            "## 📋 Active Tasks",
+            "| Trace ID | Task | Agent | Priority | Status |",
+            "| :--- | :--- | :--- | :--- | :--- |",
+        ];
 
-    try {
-        let memoryContent = fs.readFileSync(memoryPath, "utf8");
-
-        if (section === "HISTORY") {
-            const headers = ["## HISTORY (Persistent Memory)", "## HISTORY"];
-            let sectionIndex = -1;
-            for (const h of headers) {
-                sectionIndex = memoryContent.indexOf(h);
-                if (sectionIndex !== -1) {
-                    break;
-                }
+        tasks.forEach(t => {
+            if (t.status !== "COMPLETED") {
+                lines.push(`| ${t.traceId} | ${t.description} | ${t.agent} | ${t.priority} | ${t.status} |`);
             }
+        });
 
-            if (sectionIndex === -1) {
-                console.error("❌ Error: HISTORY section not found.");
-                return;
-            }
-            const headerEnd = memoryContent.indexOf("\n", sectionIndex) + 1;
-            memoryContent =
-                memoryContent.slice(0, headerEnd) +
-                `\n${content.trim()}\n` +
-                memoryContent.slice(headerEnd);
-
-            // --- Auto-Prune Logic ---
-            const historySplit = memoryContent.split("### ");
-            if (historySplit.length > 11) { // Title + 10 entries
-                const frameworkDir = path.dirname(memoryPath);
-                const archiveDir = path.join(frameworkDir, "archive/history");
-                if (!fs.existsSync(archiveDir)) fs.mkdirSync(archiveDir, { recursive: true });
-
-                const toArchive = historySplit.slice(11); // Keep the first 10 entries (newest)
-                const preserved = historySplit.slice(0, 11);
-                
-                const archiveContent = "### " + toArchive.join("### ");
-                const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-                fs.writeFileSync(path.join(archiveDir, `history-${timestamp}.md`), archiveContent);
-                
-                memoryContent = preserved.join("### ").trim() + "\n";
-                console.warn(`📦 Auto-Pruned: ${toArchive.length} old entries moved to archive.`);
-            }
-            // ------------------------
-        } else {
-            const escaped = section.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-            const sectionRegex = new RegExp(`## ${escaped}[\\s\\S]*?(?=\\n## |$)`, "m");
-            if (!sectionRegex.test(memoryContent)) {
-                console.error(`❌ Error: Section not found: ${section}`);
-                return;
-            }
-            memoryContent = memoryContent.replace(
-                sectionRegex,
-                `## ${section}\n\n${content.trim()}\n`,
-            );
+        lines.push("", "## 🤖 Agent Statuses");
+        lines.push("| Agent | State | Active Task | Last Updated |");
+        lines.push("| :--- | :--- | :--- | :--- |");
+
+        for (const [agent, info] of Object.entries(status)) {
+            const data = info as { state: string; task: string; lastUpdated?: string };
+            lines.push(`| @${agent} | ${data.state} | ${data.task} | ${data.lastUpdated || "-"} |`);
+        }
+
+        lines.push("", "## 📜 HISTORY");
+        
+        // Add last 5 history items
+        const historyDir = path.join(storePath, "history");
+        if (fs.existsSync(historyDir)) {
+            const histFiles = fs.readdirSync(historyDir)
+                .filter(f => f.endsWith(".json"))
+                .sort()
+                .reverse()
+                .slice(0, 10);
+            
+            histFiles.forEach(f => {
+                const hist = JSON.parse(fs.readFileSync(path.join(historyDir, f), "utf8"));
+                lines.push(`### ${f.replace(".json", "")}`);
+                lines.push(hist.content);
+                lines.push("");
+            });
         }
 
-        fs.writeFileSync(memoryPath, memoryContent);
-        console.warn(`✅ Section ${section} updated in PROJECT_MEMORY.md`);
-    } finally {
-        releaseMemoryLock(lockPath);
+        writeTextFile(mdPath, lines.join("\n"));
+        logger.debug("Markdown memory synchronized.");
+    } catch (err) {
+        logger.debug("Markdown memory sync failed", err);
     }
 }
 
-export function readActiveTraceId(memoryContent: string): string | null {
-    const match = memoryContent.match(/Trace ID:\s*([A-Z0-9]+)/i) ||
-                  memoryContent.match(/Trace ID\s*\|.*\|\s*\n\|.*\|.*\|.*\|\s*([A-Z0-9]+)\s*\|/i) ||
-                  memoryContent.match(/Active Trace ID[:\s|]+([A-Z0-9]+)/i);
-    return match ? match[1] : null;
-}
 
+export function acquireMemoryLock(lockPath: string): boolean {
+    try {
+        fs.writeFileSync(lockPath, String(Date.now()), { flag: "wx" });
+        return true;
+    } catch (err: unknown) {
+        const error = err as { code?: string };
+        if (error.code === "EEXIST") {
+            try {
+                const stat = fs.statSync(lockPath);
+                if (Date.now() - stat.mtimeMs > 10000) {
+                    fs.unlinkSync(lockPath);
+                    fs.writeFileSync(lockPath, String(Date.now()), { flag: "wx" });
+                    return true;
+                }
+            } catch {
+                // Ignore
+            }
+        }
+        return false;
+    }
+}
 
+export function releaseMemoryLock(lockPath: string): void {
+    if (fs.existsSync(lockPath)) fs.unlinkSync(lockPath);
+}

package/src/cli/utils/pkg.ts

@@ -1,5 +1,6 @@
 import fs from "fs";
 import path from "path";
+import { writeTextFile, writeJsonFile } from "./fs.js";
 
 export function getPackageVersion() {
     const root = getPackageRoot();
@@ -29,7 +30,7 @@ export function getPackageManager() {
  * Walks up from import.meta.url until it finds package.json with name === "agent-enderun".
  * This ensures getValidatorPath() and getPackageVersion() work correctly both in source tree
  * AND when the package is consumed from node_modules after `npm install agent-enderun` (global or local).
- * Critical for AL validation (validate-agent-army) and cross-adapter inits to work "kuraları npm'den".
+ * Critical for AL validation (validate-agent-army) and cross-adapter inits to work from npm.
  */
 function findAgentEnderunPackageRoot(): string {
     let current = path.dirname(new URL(import.meta.url).pathname);
@@ -43,7 +44,7 @@ function findAgentEnderunPackageRoot(): string {
         if (fs.existsSync(pkgPath)) {
             try {
                 const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
-                if (pkg.name === "agent-enderun" || pkg.name === "enderun-core") {
+                if (pkg.name === "agent-enderun") {
                     return current;
                 }
             } catch {
@@ -203,7 +204,7 @@ export function mergePackageJson(targetPath: string, sourcePath: string): void {
       initializedAt: new Date().toISOString(),
   };
 
-  fs.writeFileSync(targetPath, JSON.stringify(targetPkg, null, 2));
+  writeJsonFile(targetPath, targetPkg);
   console.warn("✅ package.json updated with Enderun scripts and dependencies.");
 }
 
@@ -226,20 +227,20 @@ export function sanitizeJson(obj: unknown, targetScope = ""): unknown {
         if (targetScope) {
             const scopeName = targetScope.startsWith("@") ? targetScope.slice(1) : targetScope;
 
-            // Handle scoped: @ai-enderun/foo -> @target/foo
-            if (typeof key === "string" && key.startsWith("@ai-enderun/")) {
-                finalKey = key.replace("@ai-enderun/", `${targetScope}/`);
+            // Handle scoped: @agent-enderun/foo -> @target/foo
+            if (typeof key === "string" && key.startsWith("@agent-enderun/")) {
+                finalKey = key.replace("@agent-enderun/", `${targetScope}/`);
             }
-            if (typeof value === "string" && value.startsWith("@ai-enderun/")) {
-                finalValue = value.replace("@ai-enderun/", `${targetScope}/`);
+            if (typeof value === "string" && value.startsWith("@agent-enderun/")) {
+                finalValue = value.replace("@agent-enderun/", `${targetScope}/`);
             }
 
-            // Handle unscoped: ai-enderun-foo -> target-foo
-            if (typeof key === "string" && key.startsWith("ai-enderun-")) {
-                finalKey = key.replace("ai-enderun-", `${scopeName}-`);
+            // Handle unscoped: agent-enderun-foo -> target-foo
+            if (typeof key === "string" && key.startsWith("agent-enderun-")) {
+                finalKey = key.replace("agent-enderun-", `${scopeName}-`);
             }
-            if (typeof value === "string" && value.startsWith("ai-enderun-")) {
-                finalValue = value.replace("ai-enderun-", `${scopeName}-`);
+            if (typeof value === "string" && value.startsWith("agent-enderun-")) {
+                finalValue = value.replace("agent-enderun-", `${scopeName}-`);
             }
       
             // Handle agent-enderun -> target (ONLY for the package name)
@@ -276,7 +277,7 @@ export function deepCleanProtocols(dir: string, targetScope = ""): void {
                 const content = fs.readFileSync(fullPath, "utf8");
                 const json = JSON.parse(content);
                 const cleaned = JSON.stringify(sanitizeJson(json, targetScope), null, 2);
-                fs.writeFileSync(fullPath, cleaned);
+                writeTextFile(fullPath, cleaned);
             } catch {
                 // ignore malformed json
             }

package/src/cli/utils/schemas.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+export const StateSchema = z.object({
+    phase: z.string(),
+    traceId: z.string(),
+    managerState: z.enum(["ACTIVE", "IDLE", "PAUSED"]),
+});
+
+export const AgentStatusSchema = z.record(z.object({
+    state: z.enum(["READY", "EXECUTING", "BLOCKED", "TIMEOUT", "WAITING", "IDLE"]),
+    task: z.string(),
+    lastUpdated: z.string().optional(),
+}));
+
+export const TaskSchema = z.object({
+    traceId: z.string(),
+    description: z.string(),
+    agent: z.string(),
+    priority: z.enum(["P1", "P2", "P3", "HIGH", "NORMAL", "LOW"]),
+    status: z.enum(["PENDING", "IN_PROGRESS", "APPROVED", "COMPLETED"]),
+    createdAt: z.string(),
+});

package/src/cli/utils/string.ts

@@ -15,13 +15,20 @@ export function insertTaskRow(memoryContent: string, row: string): string | null
     );
 }
 
-export function sanitizeTableCell(value: unknown): string {
-    return String(value)
-        .replace(/\|/g, "\\|")
-        .replace(/\r?\n/g, " ")
+export function sanitizeInput(input: string): string {
+    return String(input)
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, "\\\"")
+        .replace(/[\r\n]+/g, " ")
+        .replace(/<script\b[^>]*>([\s\S]*?)<\/script>/gim, "") 
+        .replace(/--/g, "-") 
         .trim();
 }
 
+export function sanitizeTableCell(value: unknown): string {
+    return sanitizeInput(String(value)).replace(/\|/g, "\\|");
+}
+
 export function normalizeAgentName(agent?: unknown): string {
     return String(agent || "manager").replace(/^@+/, "").trim() || "manager";
 }

package/src/cli/utils/ui.ts

@@ -1,7 +1,7 @@
 import chalk from "chalk";
 
 /**
- * Professional UI Utilities for Enderun Core CLI.
+ * Professional UI Utilities for Agent Enderun CLI.
  * Standardizes headers, status boxes, and strategic intent reporting.
  */
 
@@ -19,15 +19,18 @@ export const UI = {
      */
     agentBox: (agentName: string, action: string, details?: string) => {
         const width = process.stdout.columns || 80;
-        const line = "─".repeat(width - 2);
+        const line = "─".repeat(Math.max(0, width - 2));
         
         console.warn(chalk.gray(`╭${line}╮`));
-        console.warn(`${chalk.gray("│")} ${chalk.bold.yellow("≡")} ${chalk.white(`Running Agent: ${chalk.bold.green(agentName)}...`)} ${chalk.gray("(ctrl+o to expand)".padStart(width - agentName.length - 27))} ${chalk.gray("│")}`);
+        const padding = Math.max(0, width - agentName.length - 27);
+        console.warn(`${chalk.gray("│")} ${chalk.bold.yellow("≡")} ${chalk.white(`Running Agent: ${chalk.bold.green(agentName)}...`)} ${chalk.gray("(ctrl+o to expand)".padStart(padding))} ${chalk.gray("│")}`);
         if (action) {
-            console.warn(`${chalk.gray("│")} ${chalk.blue("!")} ${chalk.cyan(action)} ${" ".repeat(width - action.length - 6)} ${chalk.gray("│")}`);
+            const paddingAction = Math.max(0, width - action.length - 6);
+            console.warn(`${chalk.gray("│")} ${chalk.blue("!")} ${chalk.cyan(action)} ${" ".repeat(paddingAction)} ${chalk.gray("│")}`);
         }
         if (details) {
-            console.warn(`${chalk.gray("│")}   ${chalk.gray(details.slice(0, width - 10))} ${" ".repeat(width - details.length - 7)} ${chalk.gray("│")}`);
+            const paddingDetails = Math.max(0, width - details.length - 7);
+            console.warn(`${chalk.gray("│")}   ${chalk.gray(details.slice(0, width - 10))} ${" ".repeat(paddingDetails)} ${chalk.gray("│")}`);
         }
         console.warn(chalk.gray(`╰${line}╯`));
     },

package/src/contracts/index.ts

@@ -0,0 +1 @@
+export * from "./tasks.js";

package/src/contracts/tasks.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+
+/**
+ * Standard request contract sent to an agent.
+ */
+export const TaskRequestSchema = z.object({
+    traceId: z.string(),
+    task: z.string(),
+    priority: z.enum(["P1", "P2", "P3", "HIGH", "NORMAL", "LOW"]),
+    agent: z.string(),
+    context: z.record(z.unknown()).optional(),
+});
+
+export type TaskRequest = z.infer<typeof TaskRequestSchema>;
+
+/**
+ * Standard response contract sent back by an agent.
+ */
+export const TaskResponseSchema = z.object({
+    traceId: z.string(),
+    status: z.enum(["SUCCESS", "FAILED", "RETRY", "WAITING_FOR_APPROVAL"]),
+    message: z.string().optional(),
+    errorCode: z.string().optional(),
+});
+
+export type TaskResponse = z.infer<typeof TaskResponseSchema>;

package/src/modules/adapters/definitions.ts

@@ -1,5 +1,5 @@
 import path from "path";
-import type { AdapterConfig, AdapterId } from "../../cli/adapters/types.js";
+import type { AdapterConfig, AdapterId } from "./types.js";
 import { addMcpServerToClaude, findClaudeConfigPath } from "../../cli/utils/claude.js";
 import { writeJsonFile } from "../../shared/fs.js";
 import { registerGlobalAntigravityPlugins } from "./shared.js";