norn-cli 4.3.1 → 4.4.0

package/README.md

@@ -27,7 +27,7 @@ That means you can:
 - `.nornenv` files for environments and secrets
 - `.nornapi` files for reusable endpoint definitions
 - `.nornsql` files for database queries and commands
-- `.nornagent` files for contract-checked AI agents and model-directed delegation
+- `.nornai` or `.nornagent` files for contract-checked AI agents and model-directed delegation
 - syntax highlighting, IntelliSense, and diagnostics
 - response inspection, JSON diffing, and click-to-generate assertions
 - tagged and parameterized test execution in VS Code and the CLI
@@ -140,7 +140,7 @@ Norn can call MCP tools from sequences without leaving the `.norn` runtime. MCP
 
 A server can be declared in two places, and an alias resolves through them in this order:
 
-1. an `mcp <Alias> ... end mcp` block in a `.nornagent` sidecar the file imports — see
+1. an `mcp <Alias> ... end mcp` block in a `.nornai` sidecar the file imports — see
    [Contract-Checked Agent Graphs](#contract-checked-agent-graphs), and prefer this when agents
    use the server too, because the file then says what it connects to;
 2. `mcp.servers` in the nearest `norn.config.json`.
@@ -194,7 +194,7 @@ Behavior:
 
 ## Contract-Checked Agent Graphs
 
-Define agents in an imported `.nornagent` sidecar. An agent can grant another
+Define agents in an imported `.nornai` or `.nornagent` sidecar. Both extensions use the same syntax and behavior. An agent can grant another
 agent through `agents`; the callee then appears to the calling model as an
 ordinary tool. Its `accepts` schema constrains and validates the generated tool
 input, and its `returns` schema validates the result before it travels back up
@@ -277,7 +277,7 @@ Deterministic `run mcp` steps resolve the same aliases, so a server can be prove
 with no model and no cost:
 
 ```norn
-import "./agents.nornagent"
+import "./agents.nornai"
 
 test sequence ServersUp
     var tools = run mcp list House
@@ -290,7 +290,7 @@ shape end to end: a browser agent, a backend agent narrowed on the same custom s
 reporter, and a `judge` over the expected test cases.
 
 A prompt that outgrows its sidecar can live in its own file instead. `describe`
-and `system` both accept `file <path>`, resolved relative to the `.nornagent`
+and `system` both accept `file <path>`, resolved relative to the agent sidecar
 file just like an import:
 
 ```nornagent
@@ -309,7 +309,7 @@ Run the graph from an ordinary sequence; the same nested contract and retry
 trace appears in VS Code and the CLI:
 
 ```norn
-import "./agents.nornagent"
+import "./agents.nornai"
 
 test sequence RouteTicket
     var ticket = run readJson "./ticket.json"
@@ -370,7 +370,7 @@ fixture. `--from` accepts a unique agent name or canonical path such as
 onward runs live against the current graph.
 
 **Norn: Show Agent Graph**, or the CodeLens on any agent block, draws the graph
-for a `.nornagent` file: who calls whom, the `accepts`/`returns` contract on each
+for an agent sidecar: who calls whom, the `accepts`/`returns` contract on each
 boundary, and how each one turned out. Hover an agent or a boundary for the full
 detail — models, timings, usage, prompts, payloads, contract issues.
 

package/dist/cli.js

@@ -157480,6 +157480,12 @@ var fs36 = __toESM(require("fs"));
 var fsPromises = __toESM(require("fs/promises"));
 var path42 = __toESM(require("path"));
 
+// src/agents/agentSidecarPath.ts
+function isAgentSidecarPath(filePath) {
+  const lowerPath = filePath.toLowerCase();
+  return lowerPath.endsWith(".nornagent") || lowerPath.endsWith(".nornai");
+}
+
 // src/parser.ts
 var path4 = __toESM(require("path"));
 
@@ -158940,6 +158946,7 @@ function parseNornAgentFile(content, sourcePath) {
   let pendingMcp;
   let pendingKnowledge;
   let sawAgent = false;
+  let sawMcpDeclaration = false;
   const reportBareMcpAlias = (mcp) => {
     errors.push(parseError(
       mcp.lineNumber,
@@ -159508,6 +159515,7 @@ end model`,
       }
       const mcpMatch = trimmed.match(new RegExp(`^mcp\\s+(${IDENTIFIER})$`, "i"));
       if (mcpMatch) {
+        sawMcpDeclaration = true;
         const alias = mcpMatch[1];
         let invalid = false;
         if (sawAgent) {
@@ -159900,11 +159908,11 @@ end model`,
       "agent-knowledge-end-missing"
     ));
   }
-  if (models.size === 0) {
-    errors.push(parseError(0, "A .nornagent file must declare at least one model block.", "agent-model-required"));
+  if (!sawMcpDeclaration && models.size === 0) {
+    errors.push(parseError(0, "An agent sidecar must declare at least one model block.", "agent-model-required"));
   }
-  if (agentNames.size === 0) {
-    errors.push(parseError(0, "A .nornagent file must declare at least one agent.", "agent-required"));
+  if (!sawMcpDeclaration && agentNames.size === 0) {
+    errors.push(parseError(0, "An agent sidecar must declare at least one agent.", "agent-required"));
   }
   const localScope = new Map(agents.map((agent) => [agent.name.toLowerCase(), agent]));
   for (const validationError of validateAgentScope(localScope, { checkUnknownReferences: false })) {
@@ -160491,6 +160499,15 @@ async function resolveImports(text, baseDir, readFile4, alreadyImported = /* @__
   }
   for (const imp of imports) {
     const absolutePath = path4.resolve(baseDir, imp.path);
+    if (imp.path.toLowerCase().endsWith(".ai")) {
+      errors.push({
+        path: imp.path,
+        error: "The .ai extension is not supported for Norn agent sidecars. Rename the file to .nornai and update the import.",
+        lineNumber: imp.lineNumber,
+        blocking: true
+      });
+      continue;
+    }
     if (imp.path.endsWith(".nornsql")) {
       const importedSqlPaths = sqlImportedPathsBySource.get(sourceFilePath);
       if (importedSqlPaths.has(absolutePath)) {
@@ -160534,7 +160551,7 @@ async function resolveImports(text, baseDir, readFile4, alreadyImported = /* @__
       }
       continue;
     }
-    if (imp.path.endsWith(".nornagent")) {
+    if (isAgentSidecarPath(imp.path)) {
       const importedAgentPaths = agentImportedPathsBySource.get(sourceFilePath);
       if (importedAgentPaths.has(absolutePath)) {
         continue;
@@ -160739,7 +160756,7 @@ end sequence`);
   }
   const directAgentScope = agentDefinitionsBySource.get(sourceFilePath);
   const directAgentImportsByPath = new Map(
-    imports.filter((imp) => imp.path.toLowerCase().endsWith(".nornagent")).map((imp) => [path4.resolve(baseDir, imp.path), imp])
+    imports.filter((imp) => isAgentSidecarPath(imp.path)).map((imp) => [path4.resolve(baseDir, imp.path), imp])
   );
   for (const validationError of validateAgentScope(directAgentScope, {
     skipSameSourceChecks: true,
@@ -184867,7 +184884,7 @@ function resolveMcpServer(startPath, alias, envVariables) {
   const server = config2.servers[alias];
   if (!server) {
     throw new Error(
-      `Server alias '${alias}' was not declared by an 'mcp ${alias} ... end mcp' block in the .nornagent sidecar and was not found in ${NORN_CONFIG_FILENAME} mcp.servers`
+      `Server alias '${alias}' was not declared by an 'mcp ${alias} ... end mcp' block in the agent sidecar and was not found in ${NORN_CONFIG_FILENAME} mcp.servers`
     );
   }
   return { filePath, server };
@@ -199538,7 +199555,15 @@ var AgentInvocationRunner = class {
       throw new Error(`Agent root invocation index must be a positive integer, received '${rootInvocationIndex2}'.`);
     }
     const hopPath = `${agent.name}[${rootInvocationIndex2}]`;
-    const hop = await this.invokeAgent(agent, input2, 0, void 0, [], [], hopPath);
+    const hop = await this.invokeAgent(
+      agent,
+      input2,
+      0,
+      void 0,
+      [],
+      [...this.options.initialConversation ?? []],
+      hopPath
+    );
     return { hop, definitions: [...this.definitions.values()] };
   }
   nextInvocationId() {
@@ -203394,7 +203419,7 @@ function walkSidecars(directory) {
     if (entry.isDirectory()) {
       return walkSidecars(candidate);
     }
-    return entry.isFile() && entry.name.toLowerCase().endsWith(".nornagent") ? [candidate] : [];
+    return entry.isFile() && isAgentSidecarPath(entry.name) ? [candidate] : [];
   });
 }
 function discoverKnowledgeDeclarations(projectRoot) {
@@ -206653,7 +206678,7 @@ async function runSequenceWithJar(sequenceContent, fileVariables, cookieJar, wor
           };
         }
         if (!judgeDefinition) {
-          const message = `Judge agent '${judgeName}' was not found in the .nornagent files imported directly by this .norn file.`;
+          const message = `Judge agent '${judgeName}' was not found in the agent sidecars imported directly by this .norn file.`;
           errors.push(message);
           await emitFailure(message, step);
           return {
@@ -206693,7 +206718,7 @@ async function runSequenceWithJar(sequenceContent, fileVariables, cookieJar, wor
       const scope = getCurrentAgentScope();
       const definition = scope?.get(parsedRun.agentName.toLowerCase());
       if (!definition) {
-        const message = `Agent '${parsedRun.agentName}' was not found in the .nornagent files imported directly by this .norn file.`;
+        const message = `Agent '${parsedRun.agentName}' was not found in the agent sidecars imported directly by this .norn file.`;
         errors.push(message);
         await emitFailure(message, step);
         return {
@@ -206986,7 +207011,7 @@ async function runSequenceWithJar(sequenceContent, fileVariables, cookieJar, wor
           try {
             const judgeAgent = getCurrentAgentScope()?.get(declaration.judgeAgentName.toLowerCase());
             if (!judgeAgent) {
-              throw new Error(`Judge agent '${declaration.judgeAgentName}' was not found in the .nornagent files imported directly by this .norn file.`);
+              throw new Error(`Judge agent '${declaration.judgeAgentName}' was not found in the agent sidecars imported directly by this .norn file.`);
             }
             const evaluatedSubject = evaluateSqlArgumentExpression(declaration.subjectExpression, runtimeVariables);
             if (evaluatedSubject.error) {
@@ -207147,7 +207172,7 @@ ${describeUnmetExpectations(verdict).map((line2) => `  - ${line2}`).join("\n")}`
             const scope = getCurrentAgentScope();
             agent = scope?.get(parsed.agentName.toLowerCase());
             if (!agent) {
-              throw new Error(`Agent '${parsed.agentName}' was not found in the .nornagent files imported directly by this .norn file.`);
+              throw new Error(`Agent '${parsed.agentName}' was not found in the agent sidecars imported directly by this .norn file.`);
             }
             const evaluatedInput = evaluateSqlArgumentExpression(parsed.inputExpression, runtimeVariables);
             if (evaluatedInput.error) {
@@ -212913,12 +212938,12 @@ function knowledgeCliHelp() {
   return `
 Norn knowledge membership and topic summary
 
-Usage: norn knowledge ls --explain [sidecar.nornagent]
+Usage: norn knowledge ls --explain [sidecar.nornai|sidecar.nornagent]
 
   --explain   List every source candidate as IN or OUT and name the deciding rule
   -h, --help  Show this help
 
-With no path, Norn discovers the one .nornagent sidecar declaring knowledge below the current
+With no path, Norn discovers the one .nornai or .nornagent sidecar declaring knowledge below the current
 directory, and reports every declaration it holds.
 `;
 }
@@ -212938,7 +212963,7 @@ function parseKnowledgeCliArgs(args) {
     } else if (argument.startsWith("-")) {
       throw new Error(`Unknown knowledge option '${argument}'.`);
     } else if (options.target) {
-      throw new Error(`Unexpected knowledge argument '${argument}'. Provide at most one .nornagent path.`);
+      throw new Error(`Unexpected knowledge argument '${argument}'. Provide at most one agent sidecar path.`);
     } else {
       options.target = argument;
     }
@@ -212955,14 +212980,14 @@ function discoverSidecars(directory) {
     if (entry.isDirectory()) {
       return SKIPPED_DIRECTORIES3.has(entry.name) ? [] : discoverSidecars(entryPath);
     }
-    return entry.isFile() && entry.name.toLowerCase().endsWith(".nornagent") ? [entryPath] : [];
+    return entry.isFile() && isAgentSidecarPath(entry.name) ? [entryPath] : [];
   });
 }
 function resolveSidecar(target) {
   const resolved = path40.resolve(target ?? process.cwd());
   if (fs34.existsSync(resolved) && fs34.statSync(resolved).isFile()) {
-    if (!resolved.toLowerCase().endsWith(".nornagent")) {
-      throw new Error(`Knowledge target '${target}' is not a .nornagent sidecar.`);
+    if (!isAgentSidecarPath(resolved)) {
+      throw new Error(`Knowledge target '${target}' is not a .nornai or .nornagent sidecar.`);
     }
     return resolved;
   }
@@ -212979,11 +213004,11 @@ function resolveSidecar(target) {
     }
   });
   if (matches.length === 0) {
-    throw new Error(`No .nornagent knowledge declaration was found below '${resolved}'.`);
+    throw new Error(`No agent sidecar knowledge declaration was found below '${resolved}'.`);
   }
   if (matches.length > 1) {
     throw new Error(
-      `More than one .nornagent knowledge declaration was found. Provide one explicitly:
+      `More than one agent sidecar knowledge declaration was found. Provide one explicitly:
 ` + matches.map((match2) => `  ${path40.relative(resolved, match2)}`).join("\n")
     );
   }
@@ -213869,7 +213894,7 @@ Usage: norn <file.norn|directory> [options]
        norn replay <recording.json> [--json] [--from <agent-or-hop>] [--env <name>]
        norn secrets <command> [options]
        norn contracts <sync|check> <file.nornapi> [options]
-       norn knowledge ls --explain [sidecar.nornagent]
+       norn knowledge ls --explain [sidecar.nornai|sidecar.nornagent]
 
   When given a directory, recursively discovers .norn test sequences within
   that directory and subdirectories.
@@ -214296,7 +214321,7 @@ async function main() {
   }
   const args = rawArgs[0] === "run" ? rawArgs.slice(1) : rawArgs;
   if (args.length === 1 && (args[0] === "--version" || args[0] === "-V")) {
-    console.log(`Norn CLI ${"4.3.0"}`);
+    console.log(`Norn CLI ${"4.4.0"}`);
     return;
   }
   if (args.length === 0) {

package/dist/knowledgeIndexWorker.js

@@ -7320,6 +7320,12 @@ function queryKnowledgeEditorFacts(query, options = {}) {
   }
 }
 
+// src/agents/agentSidecarPath.ts
+function isAgentSidecarPath(filePath) {
+  const lowerPath = filePath.toLowerCase();
+  return lowerPath.endsWith(".nornagent") || lowerPath.endsWith(".nornai");
+}
+
 // src/knowledge/knowledgeIndexBuilder.ts
 var fs8 = __toESM(require("fs"));
 var path10 = __toESM(require("path"));
@@ -7878,6 +7884,7 @@ function parseNornAgentFile(content, sourcePath) {
   let pendingMcp;
   let pendingKnowledge;
   let sawAgent = false;
+  let sawMcpDeclaration = false;
   const reportBareMcpAlias = (mcp) => {
     errors.push(parseError(
       mcp.lineNumber,
@@ -8446,6 +8453,7 @@ end model`,
       }
       const mcpMatch = trimmed.match(new RegExp(`^mcp\\s+(${IDENTIFIER})$`, "i"));
       if (mcpMatch) {
+        sawMcpDeclaration = true;
         const alias = mcpMatch[1];
         let invalid = false;
         if (sawAgent) {
@@ -8838,11 +8846,11 @@ end model`,
       "agent-knowledge-end-missing"
     ));
   }
-  if (models.size === 0) {
-    errors.push(parseError(0, "A .nornagent file must declare at least one model block.", "agent-model-required"));
+  if (!sawMcpDeclaration && models.size === 0) {
+    errors.push(parseError(0, "An agent sidecar must declare at least one model block.", "agent-model-required"));
   }
-  if (agentNames.size === 0) {
-    errors.push(parseError(0, "A .nornagent file must declare at least one agent.", "agent-required"));
+  if (!sawMcpDeclaration && agentNames.size === 0) {
+    errors.push(parseError(0, "An agent sidecar must declare at least one agent.", "agent-required"));
   }
   const localScope = new Map(agents.map((agent) => [agent.name.toLowerCase(), agent]));
   for (const validationError of validateAgentScope(localScope, { checkUnknownReferences: false })) {
@@ -10413,7 +10421,7 @@ function walkSidecars(directory) {
     if (entry.isDirectory()) {
       return walkSidecars(candidate);
     }
-    return entry.isFile() && entry.name.toLowerCase().endsWith(".nornagent") ? [candidate] : [];
+    return entry.isFile() && isAgentSidecarPath(entry.name) ? [candidate] : [];
   });
 }
 function discoverKnowledgeDeclarations(projectRoot) {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "norn-cli",
   "displayName": "Norn",
-  "description": "Version-controlled API and database tests. Author in VS Code, then run the same files from the CLI and CI.",
-  "version": "4.3.1",
+  "description": "Build version-controlled agentic flows in VS Code and run them from the CLI or CI.",
+  "version": "4.4.0",
   "publisher": "Norn-PeterKrustanov",
   "author": {
     "name": "Peter Krastanov"
@@ -48,6 +48,7 @@
     "onLanguage:nornk8s",
     "onLanguage:nornagent",
     "workspaceContains:**/*.nornagent",
+    "workspaceContains:**/*.nornai",
     "workspaceContains:**/norn.config.json",
     "onChatParticipant:norn.chat",
     "onView:norn.sidebarHome",
@@ -55,12 +56,12 @@
     "onCommand:norn.importPostmanEnvironment",
     "onCommand:norn.createStarterCatalog",
     "onCommand:norn.createSqlStarterFiles",
-    "onCommand:norn.createMcpStarterConfig",
     "onCommand:norn.openTerminal",
     "onCommand:norn.terminal.focusRawTerminal",
     "onCommand:norn.debugSequence",
     "onCommand:norn.debug.runToNextContractFailure",
     "onCommand:norn.showAgentGraph",
+    "onCommand:norn.chatWithAgent",
     "onCommand:norn.showAgentRunResults",
     "onDebugResolve:norn"
   ],
@@ -93,6 +94,11 @@
         "title": "Show Agent Graph",
         "category": "Norn"
       },
+      {
+        "command": "norn.chatWithAgent",
+        "title": "Chat With Agent",
+        "category": "Norn"
+      },
       {
         "command": "norn.showAgentRunResults",
         "title": "Show Agent Run Results",
@@ -136,7 +142,11 @@
       {
         "command": "norn.openTerminal",
         "title": "Open Terminal",
-        "category": "Norn"
+        "category": "Norn",
+        "icon": {
+          "light": "./images/nornapi-icon.svg",
+          "dark": "./images/nornapi-icon.svg"
+        }
       },
       {
         "command": "norn.terminal.focusRawTerminal",
@@ -188,11 +198,6 @@
         "title": "Open Norn Starter Catalogue",
         "category": "Norn"
       },
-      {
-        "command": "norn.createMcpStarterConfig",
-        "title": "Create MCP Starter Config",
-        "category": "Norn"
-      },
       {
         "command": "norn.encryptSecretAtLine",
         "title": "Encrypt Secret At Line",
@@ -262,11 +267,6 @@
           "command": "norn.createStarterCatalog",
           "when": "explorerResourceIsFolder",
           "group": "norn@1"
-        },
-        {
-          "command": "norn.createMcpStarterConfig",
-          "when": "explorerResourceIsFolder",
-          "group": "norn@2"
         }
       ],
       "debug/toolBar": [
@@ -275,6 +275,12 @@
           "when": "debugType == norn && debugState == stopped",
           "group": "navigation@25"
         }
+      ],
+      "editor/title": [
+        {
+          "command": "norn.openTerminal",
+          "group": "navigation"
+        }
       ]
     },
     "languages": [
@@ -359,7 +365,8 @@
           "nornagent"
         ],
         "extensions": [
-          ".nornagent"
+          ".nornagent",
+          ".nornai"
         ],
         "icon": {
           "light": "./images/nornagent-icon.svg",

package/schemas/norn.config.schema.json

@@ -486,7 +486,7 @@
     "agentsSection": {
       "type": "object",
       "additionalProperties": false,
-      "description": "Global recording behavior and global/provider-specific limits for agent runs. Per-agent .nornagent directives override limit values.",
+      "description": "Global recording behavior and global/provider-specific limits for agent runs. Per-agent .nornai or .nornagent directives override limit values.",
       "properties": {
         "_comment": {
           "$ref": "#/definitions/comment",