using geniascript runtime outside the cli

.github/workflows/build.yml

@@ -38,7 +38,8 @@ jobs:
                   GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
             - name: compile tests
               run: pnpm run test:compile
-              continue-on-error: true
+            - name: runtime tests
+              run: pnpm run test:runtime
             - name: unit tests
               run: pnpm run test:samples
               env:

.gitignore

@@ -68,3 +68,5 @@ genaiscript*.tgz
 # START Ruler Generated Files
 .github/copilot-instructions.md
 # END Ruler Generated Files
+
+packages/*/src/package.json

.vscode/settings.json

@@ -40,6 +40,7 @@
         "chattypes",
         "Chunker",
         "chunkers",
+        "clihelp",
         "cmds",
         "cmsg",
         "codelion",
@@ -95,6 +96,7 @@
         "fallbacktools",
         "fetchtext",
         "ffprobe",
+        "filetree",
         "firstsecond",
         "Fmepg",
         "frontmatter",
@@ -160,6 +162,7 @@
         "makeitbetter",
         "managedidentity",
         "markdownify",
+        "markdownifypdf",
         "markitdown",
         "mcpclient",
         "mcpresource",

docs/src/content/docs/reference/runtime.mdx

@@ -0,0 +1,23 @@
+---
+title: Runtime
+sidebar:
+  order: 1.2
+description: Learn how to run GenAIScript scripts in a Node.JS environment, including configuration
+---
+
+Scripts using the `.genai.mts` (or any `.genai.*` extension) are meant to be run through the [command line interfanece](/genaiscript/reference/cli).
+
+This page describes how to use the runtime in a Node.JS script without using the CLI.
+
+## Import and configuration
+
+```js
+import { initialize } from "@genaiscript/runtime";
+
+// runs this before using any global ty\pes
+await initialize();
+```
+
+## globals
+
+The runtime installs global parsers and inline prompt types. However, the global `$`, `def`, etc... is not available, online inline prompts.

package.json

@@ -94,6 +94,8 @@
     "test:scripts": "cd packages/sample/ && pnpm test:scripts",
     "test:scripts:view": "cd packages/sample/ && pnpm test:scripts:view",
     "test:system": "cd packages/core && node ../cli/dist/src/index.js scripts compile",
+    "test:runtime": "cd packages/runtime && pnpm run test",
+    "tsx": "tsx",
     "typecheck": "echo skipped",
     "typecheck:web": "pnpm --filter=@genaiscript/web run typecheck",
     "whisper": "pnpm whisper:stop && pnpm whisper:start",
@@ -108,7 +110,7 @@
     }
   },
   "devDependencies": {
-    "@inquirer/prompts": "^7.5.3",
+    "@inquirer/prompts": "catalog:",
     "@intellectronica/ruler": "^0.2.3",
     "@modelcontextprotocol/inspector": "^0.14.3",
     "npm-check-updates": "^18.0.1",
@@ -117,6 +119,7 @@
     "prettier": "catalog:",
     "prettier-plugin-curly": "^0.3.2",
     "tailwindcss": "^4.1.10",
+    "tsx": "catalog:",
     "turbo": "^2.5.4",
     "zx": "catalog:"
   }

packages/api/src/run.ts

@@ -512,7 +512,7 @@ export async function runScriptInternal(
       topLogprobs,
       fenceFormat,
       runDir,
-      applyGitIgnore,      
+      applyGitIgnore,
       cliInfo: options.cli
         ? {
             files,

packages/cli/package.json

@@ -39,7 +39,7 @@
     "@genaiscript/api": "workspace:*",
     "@genaiscript/core": "workspace:*",
     "@genaiscript/runtime": "workspace:*",
-    "@inquirer/prompts": "^7.5.3",
+    "@inquirer/prompts": "catalog:",
     "@modelcontextprotocol/sdk": "^1.13.1",
     "chokidar": "^4.0.3",
     "commander": "^12.1.0",

packages/cli/src/action.ts

@@ -260,7 +260,12 @@ export async function actionConfigure(
   ].filter(Boolean);
 
   const actionYmlFilename = resolve(out, "action.yml");
-  const action = YAMLTryParse(await tryReadText(actionYmlFilename));
+  const action = YAMLTryParse(await tryReadText(actionYmlFilename)) as {
+    description?: string;
+    inputs?: Record<string, GitHubActionFieldType>;
+    outputs?: Record<string, GitHubActionFieldType>;
+    branding?: Record<string, unknown>;
+  };
   if (action && !force) {
     logVerbose(`updating action.yml`);
     action.description = script.description || pkg?.description;

packages/core/package.json

@@ -124,7 +124,7 @@
     "toml": "^3.0.0",
     "ts-dedent": "^2.2.0",
     "tslib": "catalog:",
-    "tsx": "^4.19.4",
+    "tsx": "catalog:",
     "turndown": "^7.2.0",
     "turndown-plugin-gfm": "^1.0.2",
     "undici": "^7.10.0",

packages/core/src/agent.ts

@@ -111,7 +111,7 @@ export async function agentAddMemory(
   };
   dbg(`add ${agent}: ${ellipse(query, 80)} -> ${ellipse(text, 128)}`);
   await cache.set(cacheKey, cachedValue);
-  trace.detailsFenced(
+  trace?.detailsFenced(
     `🧠 agent memory: ${HTMLEscape(query)}`,
     HTMLEscape(prettifyMarkdown(cachedValue.answer)),
     "markdown",
@@ -139,25 +139,26 @@ export async function traceAgentMemory(
   options: Pick<GenerationOptions, "userState"> & Required<TraceOptions>,
 ) {
   const { trace } = options || {};
+  if (!trace) return;
   const cache = agentCreateCache({
     userState: options.userState,
     lookupOnly: true,
   });
   const memories = await loadMemories(cache);
   if (memories?.length) {
     try {
-      trace.startDetails("🧠 agent memory");
+      trace?.startDetails("🧠 agent memory");
       memories
         .reverse()
         .forEach(({ agent, query, answer }) =>
-          trace.detailsFenced(
+          trace?.detailsFenced(
             `👤 ${agent}: ${HTMLEscape(query)}`,
             HTMLEscape(prettifyMarkdown(answer)),
             "markdown",
           ),
         );
     } finally {
-      trace.endDetails();
+      trace?.endDetails();
     }
   }
 }

packages/core/src/anthropic.ts

@@ -160,6 +160,7 @@ const convertAssistantMessage = (
             signature: msg.signature,
           } satisfies Anthropic.ThinkingBlockParam)
         : undefined,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       ...((convertStandardMessage(msg)?.content || []) as any),
       ...(msg.tool_calls || []).map(
         (tool) =>
@@ -305,7 +306,7 @@ const completerFactory = (
     const httpAgent = await resolveHttpProxyAgent();
     const messagesApi = await resolver(trace, cfg, httpAgent, fetch);
     dbg("caching", caching);
-    trace.itemValue(`caching`, caching);
+    trace?.itemValue(`caching`, caching);
 
     let numTokens = 0;
     let chatResp = "";
@@ -363,8 +364,8 @@ const completerFactory = (
     }
 
     dbgMessages(`messages: %O`, messages);
-    trace.detailsFenced("✉️ body", mreq, "json");
-    trace.appendContent("\n");
+    trace?.detailsFenced("✉️ body", mreq, "json");
+    trace?.appendContent("\n");
 
     try {
       const stream = messagesApi.stream({ ...mreq, ...headers });
@@ -399,17 +400,17 @@ const completerFactory = (
                 break;
               case "thinking_delta":
                 reasoningContent = chunk.delta.thinking;
-                trace.appendToken(reasoningContent);
+                trace?.appendToken(reasoningContent);
                 reasoningChatResp += reasoningContent;
-                trace.appendToken(chunkContent);
+                trace?.appendToken(chunkContent);
                 break;
               case "text_delta":
                 if (!chunk.delta.text) dbg(`empty text_delta`, chunk);
                 else {
                   chunkContent = chunk.delta.text;
                   numTokens += approximateTokens(chunkContent, { encoder });
                   chatResp += chunkContent;
-                  trace.appendToken(chunkContent);
+                  trace?.appendToken(chunkContent);
                 }
                 break;
 
@@ -448,13 +449,13 @@ const completerFactory = (
     } catch (e) {
       finishReason = "fail";
       logError(e);
-      trace.error("error while processing event", serializeError(e));
+      trace?.error("error while processing event", serializeError(e));
     }
 
-    trace.appendContent("\n\n");
-    trace.itemValue(`🏁 finish reason`, finishReason);
+    trace?.appendContent("\n\n");
+    trace?.itemValue(`🏁 finish reason`, finishReason);
     if (usage?.total_tokens) {
-      trace.itemValue(
+      trace?.itemValue(
         `🪙 tokens`,
         `${usage.total_tokens} total, ${usage.prompt_tokens} prompt, ${usage.completion_tokens} completion`,
       );
@@ -472,7 +473,7 @@ const completerFactory = (
   return completion;
 };
 
-const listModels: ListModelsFunction = async (cfg, options) => {
+const listModels: ListModelsFunction = async (cfg) => {
   try {
     const anthropic = new Anthropic({
       baseURL: cfg.base,
@@ -507,9 +508,10 @@ export const AnthropicModel = Object.freeze<LanguageModel>({
       fetch,
       fetchOptions: {
         dispatcher: httpAgent,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
       } as RequestInit as any,
     });
-    if (anthropic.baseURL) trace.itemValue(`url`, `[${anthropic.baseURL}](${anthropic.baseURL})`);
+    if (anthropic.baseURL) trace?.itemValue(`url`, `[${anthropic.baseURL}](${anthropic.baseURL})`);
     const messagesApi = anthropic.beta.messages;
     return messagesApi;
   }),
@@ -524,9 +526,10 @@ export const AnthropicBedrockModel = Object.freeze<LanguageModel>({
       fetch,
       fetchOptions: {
         dispatcher: httpAgent,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
       } as RequestInit as any,
     });
-    if (anthropic.baseURL) trace.itemValue(`url`, `[${anthropic.baseURL}](${anthropic.baseURL})`);
+    if (anthropic.baseURL) trace?.itemValue(`url`, `[${anthropic.baseURL}](${anthropic.baseURL})`);
     return anthropic.beta.messages;
   }),
   id: MODEL_PROVIDER_ANTHROPIC_BEDROCK,