loopengine 0.1.95 → 0.1.97

package/README.md

@@ -402,16 +402,35 @@ you, using the matching API key from the environment:
 | `'kimi'` | `MOONSHOT_API_KEY` | yes |
 | `'glm'` | `GLM_API_KEY` | yes |
 | `'gemini'` | `GEMINI_API_KEY` | yes |
+| `'xai'` | `XAI_API_KEY` | yes |
+| `'meta'` | `META_API_KEY` | yes |
 
 `'kimi'`'s env var is `MOONSHOT_API_KEY`, not `KIMI_API_KEY` — deliberate,
 matching Moonshot AI's own docs (the API/company behind Kimi) rather than
-this package's own provider name. `openai`/`deepseek`/`kimi`/`glm`/
-`gemini` all reuse the same OpenAI-Chat-Completions-compatible request
+this package's own provider name. `'meta'` (Meta's Muse models, e.g.
+`muse-spark-1.3`, through the Meta Model API) reads `META_API_KEY`,
+LiteLLM's name, rather than the generic `MODEL_API_KEY` in Meta's own
+examples. `openai`/`deepseek`/`kimi`/`glm`/`gemini`/`xai`/`meta` all reuse the same OpenAI-Chat-Completions-compatible request
 translation, just pointed at each provider's own base URL — see
 `core/model-calls/*.ts` for the provider-specific details (base URLs,
 `max_completion_tokens` vs `max_tokens`, and Gemini's own "still in beta"
 caveat on Google's compatibility layer).
 
+The console's model dropdown (New agent, and an agent's Model > Edit)
+lists each provider's models live from its API once its key is saved. To
+choose the list yourself, add a `models.yaml` next to `.env` mapping each
+provider to its models; a provider listed there offers exactly those, in
+that order, with no key needed, and edits show the next time the
+dropdown loads (`LOOPENGINE_MODELS_FILE` points at a different file):
+
+```yaml
+anthropic:
+  - claude-opus-5-5
+  - claude-sonnet-5-5
+deepseek:
+  - deepseek-v4-pro
+```
+
 For anything else (a custom SDK client, a canned/simulated model for
 testing), export your own `createModelCall(): ModelCall` instead.
 

package/dist/bin/ability-manager.d.ts

@@ -133,6 +133,10 @@ export declare function backfillDependencies(agentName: string, abilityName: str
  * real network call is needed there; see ABILITIES.md's "Publishing an
  * ability" section). */
 export declare function fetchAbilityDir(spec: string): string;
+/** fetchAbilityDir without blocking the server while npm and git run:
+ * for browsing (the console's ability details), where an install's
+ * stop-the-world fetch would freeze every other request. */
+export declare function fetchAbilityDirAsync(spec: string): Promise<string>;
 export interface FetchOptions {
     fetchAbilityDir?: (spec: string) => string;
     /** Test-only override for the installing project's own "loopengine"

package/dist/bin/ability-manager.js

@@ -17,13 +17,15 @@
 // direction worth introducing to share ~30 lines (see ABILITIES.md's
 // "Upgrading" section).
 import { createHash } from 'node:crypto';
-import { execFileSync } from 'node:child_process';
+import { execFile, execFileSync } from 'node:child_process';
+import { promisify } from 'node:util';
 import { basename, dirname, join } from 'node:path';
 import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { parse as parseYaml } from 'yaml';
 import semver from 'semver';
 import { agentDir } from '../core/gateway-tools.js';
+import { abilityFetchAuth } from '../core/ability-sources.js';
 import { addToolToIndex, removeToolFromIndex, toCamelCase } from '../web/http-tool-admin.js';
 import { addActauthRule, updateActauthRule, removeActauthRule, readActauthConfig } from '../web/actauth-admin.js';
 export class AbilityManifestError extends Error {
@@ -213,7 +215,15 @@ function sha256(content) {
  * ability" section). */
 export function fetchAbilityDir(spec) {
     const workDir = mkdtempSync(join(tmpdir(), 'loopengine-ability-'));
-    execFileSync('npm', ['pack', spec, '--pack-destination', workDir], { stdio: 'pipe' });
+    // The private sources' tokens (core/ability-sources.ts), only for this
+    // npm pack: never in the spec, so they aren't written anywhere.
+    const auth = abilityFetchAuth();
+    try {
+        execFileSync('npm', ['pack', spec, '--pack-destination', workDir, ...auth.args], { stdio: 'pipe', env: auth.env });
+    }
+    finally {
+        auth.cleanup();
+    }
     const tarball = readdirSync(workDir).find((f) => f.endsWith('.tgz'));
     if (!tarball) {
         throw new Error(`Could not fetch '${spec}' — check the package exists and is reachable (registry auth / git credentials / local path).`);
@@ -225,6 +235,28 @@ export function fetchAbilityDir(spec) {
     execFileSync('tar', ['-xzf', join(workDir, tarball), '-C', workDir], { stdio: 'pipe' });
     return join(workDir, 'package');
 }
+/** fetchAbilityDir without blocking the server while npm and git run:
+ * for browsing (the console's ability details), where an install's
+ * stop-the-world fetch would freeze every other request. */
+export async function fetchAbilityDirAsync(spec) {
+    const workDir = mkdtempSync(join(tmpdir(), 'loopengine-ability-'));
+    const auth = abilityFetchAuth();
+    try {
+        await promisify(execFile)('npm', ['pack', spec, '--pack-destination', workDir, ...auth.args], { env: auth.env, timeout: 120_000 });
+    }
+    catch {
+        rmSync(workDir, { recursive: true, force: true });
+        throw new Error(`Could not fetch '${spec}' — check the package exists and is reachable (registry auth / git credentials / local path).`);
+    }
+    finally {
+        auth.cleanup();
+    }
+    const tarball = readdirSync(workDir).find((f) => f.endsWith('.tgz'));
+    if (!tarball)
+        throw new Error(`Could not fetch '${spec}'.`);
+    await promisify(execFile)('tar', ['-xzf', join(workDir, tarball), '-C', workDir]);
+    return join(workDir, 'package');
+}
 function readManifest(abilityDir) {
     const manifestPath = join(abilityDir, 'loopengine.ability.json');
     if (!existsSync(manifestPath)) {

package/dist/bin/cli.d.ts

@@ -7,7 +7,7 @@ export declare class AgentNotFoundError extends Error {
 }
 export declare class AgentModelError extends Error {
 }
-type Provider = 'anthropic' | 'openai' | 'deepseek' | 'kimi' | 'glm' | 'gemini';
+type Provider = 'anthropic' | 'openai' | 'deepseek' | 'kimi' | 'glm' | 'gemini' | 'xai' | 'meta';
 export interface AgentTemplateOptions {
     systemPrompt?: string;
     model?: {

package/dist/bin/cli.js

@@ -32,6 +32,9 @@ const MODEL_ENV_VAR = {
     kimi: 'MOONSHOT_API_KEY',
     glm: 'GLM_API_KEY',
     gemini: 'GEMINI_API_KEY',
+    xai: 'XAI_API_KEY',
+    // LiteLLM's name; see core/model-calls/meta-model-call.ts.
+    meta: 'META_API_KEY',
 };
 // Escapes a value for safe interpolation into a single-quoted TS string
 // literal in generated code — an operator-supplied systemPrompt (from

package/dist/core/ability-details.d.ts

@@ -0,0 +1,31 @@
+export type Decision = 'allow' | 'ask' | 'deny';
+export interface AbilityToolDetails {
+    name: string;
+    description: string;
+    /** The decision the ability ships for it (its actauth rules), if any. */
+    decision?: Decision;
+}
+export interface AbilitySkillDetails {
+    name: string;
+    description: string;
+}
+export interface AbilityDetails {
+    name: string;
+    version: string;
+    description: string;
+    tools: AbilityToolDetails[];
+    skills: AbilitySkillDetails[];
+    /** Settings it reads (env var names), with a description when given. */
+    settings: Array<{
+        name: string;
+        description?: string;
+    }>;
+}
+/** Throws when `dir` holds no loopengine.ability.json. */
+export declare function readAbilityDetails(dir: string): AbilityDetails;
+/** The { name, description } of every object literal in a tool file that
+ * has both as string values: its ToolDefinition(s). Parsed, never run. */
+export declare function readToolDefinitions(source: string, fileName?: string): Array<{
+    name: string;
+    description: string;
+}>;

package/dist/core/ability-details.js

@@ -0,0 +1,140 @@
+// What an ability can do, read from its files without running any of
+// them: its tools (name and description, taken from each tool file's
+// ToolDefinition with the TypeScript parser), the permission each tool
+// ships with (its actauth rules), and its skills (each SKILL.md's
+// frontmatter). Backs the console's ability details.
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import ts from 'typescript';
+import { parse as parseYaml } from 'yaml';
+/** Throws when `dir` holds no loopengine.ability.json. */
+export function readAbilityDetails(dir) {
+    const manifestPath = join(dir, 'loopengine.ability.json');
+    if (!existsSync(manifestPath))
+        throw new Error('This package has no loopengine.ability.json, so it isn\'t a loopengine ability');
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    let pkg = {};
+    try {
+        pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+    }
+    catch { }
+    const decisions = readShippedDecisions(dir, manifest.actauth);
+    const tools = strings(manifest.tools).flatMap((file) => {
+        const path = join(dir, file);
+        const found = existsSync(path) ? readToolDefinitions(readFileSync(path, 'utf8'), file) : [];
+        // A file whose definition can't be read statically still shows, by its file name.
+        const listed = found.length ? found : [{ name: basename(file).replace(/\.[cm]?[jt]s$/, ''), description: '' }];
+        return listed.map((tool) => (decisions[tool.name] ? { ...tool, decision: decisions[tool.name] } : tool));
+    });
+    const skills = strings(manifest.skills).map((skillDir) => readSkill(join(dir, skillDir), skillDir));
+    return { name: pkg.name || basename(dir), version: pkg.version || '', description: pkg.description || '', tools, skills, settings: readSettings(manifest) };
+}
+function strings(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === 'string') : [];
+}
+/** Each tool rule's decision, by tool name, from the ability's own rules
+ * file (a list of { tool, decision }, or { rules: [...] }). */
+function readShippedDecisions(dir, actauth) {
+    if (typeof actauth !== 'string' || !existsSync(join(dir, actauth)))
+        return {};
+    let parsed;
+    try {
+        parsed = parseYaml(readFileSync(join(dir, actauth), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+    const rules = Array.isArray(parsed) ? parsed : Array.isArray(parsed?.rules) ? parsed.rules : [];
+    const out = {};
+    for (const rule of rules) {
+        if (typeof rule?.tool === 'string' && (rule.decision === 'allow' || rule.decision === 'ask' || rule.decision === 'deny') && !out[rule.tool])
+            out[rule.tool] = rule.decision;
+    }
+    return out;
+}
+/** The { name, description } of every object literal in a tool file that
+ * has both as string values: its ToolDefinition(s). Parsed, never run. */
+export function readToolDefinitions(source, fileName = 'tool.ts') {
+    const file = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, fileName.endsWith('.js') ? ts.ScriptKind.JS : ts.ScriptKind.TS);
+    const found = [];
+    const visit = (node) => {
+        if (ts.isObjectLiteralExpression(node)) {
+            let name;
+            let description;
+            let hasSchema = false;
+            for (const prop of node.properties) {
+                if (!ts.isPropertyAssignment(prop))
+                    continue;
+                const key = ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name) ? prop.name.text : undefined;
+                if (key === 'name')
+                    name = staticString(prop.initializer);
+                else if (key === 'description')
+                    description = staticString(prop.initializer);
+                else if (key === 'input_schema' || key === 'inputSchema' || key === 'execute')
+                    hasSchema = true;
+            }
+            // A tool definition, not an input-schema property that also has a
+            // description: those have no name.
+            if (name && description !== undefined && hasSchema) {
+                found.push({ name, description });
+                return;
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(file);
+    return found;
+}
+/** A string literal, a template without substitutions, or a + of them. */
+function staticString(node) {
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+        return node.text;
+    if (ts.isParenthesizedExpression(node))
+        return staticString(node.expression);
+    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+        const left = staticString(node.left);
+        const right = staticString(node.right);
+        return left !== undefined && right !== undefined ? left + right : undefined;
+    }
+    return undefined;
+}
+function readSkill(dir, skillDir) {
+    const fallback = { name: basename(skillDir), description: '' };
+    const path = join(dir, 'SKILL.md');
+    if (!existsSync(path))
+        return fallback;
+    const match = readFileSync(path, 'utf8').match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return fallback;
+    try {
+        const front = parseYaml(match[1]);
+        return { name: typeof front?.name === 'string' ? front.name : fallback.name, description: typeof front?.description === 'string' ? front.description : '' };
+    }
+    catch {
+        return fallback;
+    }
+}
+/** The env vars an ability declares it reads, from loopengine.ability.json
+ * (`env` or `settings`: a list of names or { name, description }, or a
+ * map of name to description or { description }). */
+function readSettings(manifest) {
+    const raw = manifest.env ?? manifest.settings;
+    const out = [];
+    const add = (name, description) => {
+        if (typeof name === 'string' && name && !out.some((s) => s.name === name))
+            out.push(typeof description === 'string' && description ? { name, description } : { name });
+    };
+    if (Array.isArray(raw)) {
+        for (const entry of raw) {
+            if (typeof entry === 'string')
+                add(entry);
+            else if (entry && typeof entry === 'object')
+                add(entry.name, entry.description);
+        }
+    }
+    else if (raw && typeof raw === 'object') {
+        for (const [name, value] of Object.entries(raw))
+            add(name, typeof value === 'string' ? value : value?.description);
+    }
+    return out;
+}

package/dist/core/ability-sources.d.ts

@@ -0,0 +1,59 @@
+export type AbilitySource = {
+    id: string;
+    type: 'github';
+    owner: string;
+} | {
+    id: string;
+    type: 'npm';
+    registry: string;
+    scope: string;
+} | {
+    id: string;
+    type: 'folder';
+    path: string;
+};
+export interface SourceAbility {
+    name: string;
+    description: string;
+    version: string;
+    /** What to install it with: github:owner/repo, @scope/name or file:/path. */
+    spec: string;
+}
+export interface AbilityOrigin {
+    kind: 'public' | 'private';
+    /** Where it came from, for the console's badge: "npm", "GitHub
+     * loopengine-co/lp-github", "Folder ../loopengine-abilities", ... */
+    label: string;
+}
+export declare class AbilitySourceError extends Error {
+}
+export declare const ABILITY_SOURCES_FILE_ENV = "LOOPENGINE_ABILITY_SOURCES_FILE";
+export declare function abilitySourcesPath(): string;
+/** The env var a source's token lives in. */
+export declare function sourceTokenVar(id: string): string;
+/** Throws AbilitySourceError naming the first problem. An id is made up
+ * from the source when none is given. */
+export declare function validateAbilitySource(input: unknown): AbilitySource;
+export declare function readAbilitySources(): AbilitySource[];
+/** Adds a source, or replaces the one with the same id. */
+export declare function saveAbilitySource(input: unknown): AbilitySource;
+export declare function removeAbilitySource(id: string): void;
+export declare function describeSource(source: AbilitySource): string;
+/** The abilities a source offers. GitHub and npm listings are cached for
+ * five minutes per token; a folder is read fresh. Throws with a message
+ * fit for the console when the source can't be read. */
+export declare function listSourceAbilities(source: AbilitySource, options?: {
+    fetch?: typeof fetch;
+}): Promise<SourceAbility[]>;
+/** Public (npm) or private (a source, a git repo or a local folder), from
+ * the spec it was installed with. */
+export declare function abilityOrigin(spec: string | undefined, name: string, sources?: AbilitySource[]): AbilityOrigin;
+/** What `npm pack` needs to fetch from the private sources: GitHub tokens
+ * as git URL rewrites (only in the child's env, per owner), and a
+ * temporary npm config adding each private scope's registry and token to
+ * the user's own. `cleanup` removes that file. */
+export declare function abilityFetchAuth(sources?: AbilitySource[]): {
+    args: string[];
+    env: NodeJS.ProcessEnv;
+    cleanup: () => void;
+};