loopengine 0.0.10 → 0.0.16

package/dist/{anthropic-model-call.d.ts → model-calls/anthropic-model-call.d.ts}

@@ -1,5 +1,5 @@
 import Anthropic from '@anthropic-ai/sdk';
-import type { ModelCall } from './run-agent.js';
+import type { ModelCall } from '#run-agent.js';
 export interface AnthropicModelCallOptions {
     /** Defaults to the ANTHROPIC_API_KEY env var, same as the SDK itself. */
     apiKey?: string;

package/dist/{anthropic-model-call.js → model-calls/anthropic-model-call.js}

@@ -1,9 +1,11 @@
-// The one real ModelCall implementation loopengine ships. Every example
-// agent (file-agent.ts, customer-service-agent.ts, rag-agent.ts) still
-// uses a canned, turn-counting fake so the whole loop is runnable with no
-// API key — swap that fake for createAnthropicModelCall(...) and nothing
-// in run-agent.ts, the adapters, or any AgentConfig changes. ModelCall is
-// the only seam this needed.
+// One of the real ModelCall implementations loopengine ships (see also
+// openai-model-call.ts, deepseek-model-call.ts — the latter is what
+// agents/customer-service/index.ts actually uses). file-agent.ts and
+// rag-agent.ts still use a canned, turn-counting fake so the whole loop
+// is runnable with no API key — swap that fake for
+// createAnthropicModelCall(...) and nothing in run-agent.ts, the
+// adapters, or any AgentConfig changes. ModelCall is the only seam this
+// needed.
 //
 // loopengine's own Message type mirrors Anthropic's native shape closely
 // on purpose: `content` is either a plain string or a ModelContentBlock[]

package/dist/{deepseek-model-call.d.ts → model-calls/deepseek-model-call.d.ts}

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import type { ModelCall } from './run-agent.js';
+import type { ModelCall } from '#run-agent.js';
 export interface DeepSeekModelCallOptions {
     /** Defaults to the DEEPSEEK_API_KEY env var. */
     apiKey?: string;

package/dist/{openai-model-call.d.ts → model-calls/openai-model-call.d.ts}

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import type { Message, ModelCall, ModelResponse } from './run-agent.js';
+import type { Message, ModelCall, ModelResponse } from '#run-agent.js';
 type ChatMessage = OpenAI.Chat.Completions.ChatCompletionMessageParam;
 export interface OpenAIModelCallOptions {
     /** Defaults to the OPENAI_API_KEY env var, same as the SDK itself. */

package/dist/run-agent.d.ts

@@ -1,4 +1,5 @@
-import type { AgentConfig, ToolSchema } from './agent-config.js';
+import { RuleSet } from 'actauth';
+import type { AgentConfig, ToolDefinition, ToolSchema } from '#agent-config.js';
 export interface ModelContentBlock {
     type: string;
     /** text blocks. */
@@ -38,6 +39,13 @@ export type ModelCall = (messages: Message[], system: string, tools: ToolSchema[
 export interface RunAgentOptions {
     /** Emitted at each loop step for callers that want visibility (logging, UI, tests). Default: no-op. */
     onEvent?: (event: string, detail: unknown) => void;
+    /** The ActAuth tenant this call runs as — feeds the Gate's scope, so it
+     * governs which rules apply. runAgent() never sees a request, so it
+     * can't call AgentConfig.tenantFor itself; adapters/http.ts resolves it
+     * per request and passes the result here. Default `'default'`, same as
+     * omitting it — every standalone/CLI caller (which never has a request
+     * to resolve tenantFor from) gets that default automatically. */
+    tenant?: string;
 }
 export interface RunAgentResult {
     /** Final assistant text for this turn. */
@@ -59,4 +67,26 @@ export interface RunAgentResult {
      * not something the model said. Absent on a normal finish. */
     stopReason?: 'max_turns';
 }
+/** Resolves AgentConfig.rules the same way skillsDirs resolves its own
+ * default: an inline array is used as-is (full 3-segment scopePattern,
+ * unchanged — see loadYamlRules for why only the YAML form gets the
+ * agent segment auto-appended); omitted entirely defaults to
+ * `agents/<name>/actauth.yml`, this repo's own folder-form convention.
+ * Unlike skillsDirs, a missing *default* file falls back to an empty
+ * ruleset rather than propagating the raw ENOENT — permissions failing
+ * shouldn't crash the whole call. That fallback defaults to `'deny'`, not
+ * the inline-array form's `'ask'`: no `actauth.yml` at all means this
+ * agent's permission story was never actually written, which is a
+ * stricter unknown than "written, but this one tool has no rule" — 'ask'
+ * still runs an Approver that could auto-approve, while 'deny' refuses
+ * outright until real rules exist. `defaultDecision`, if set, still wins
+ * over that. An *explicitly* given path that doesn't exist is a real
+ * configuration bug, though, and still throws — only the silent, implicit
+ * default gets this forgiveness.
+ *
+ * Exported (alongside loadDefaultTools below) so adapters/http.ts's
+ * GET /agents/:name/config route can show the same rules runAgent() would
+ * actually enforce, not a re-derived guess at them. */
+export declare function loadRules(config: AgentConfig): RuleSet;
+export declare function loadDefaultTools(config: AgentConfig): Promise<ToolDefinition[]>;
 export declare function runAgent(config: AgentConfig, modelCall: ModelCall, userMessage: string, history?: Message[], options?: RunAgentOptions): Promise<RunAgentResult>;

package/dist/run-agent.js

@@ -3,11 +3,29 @@
 // differ. runAgent itself does no I/O and holds no state between calls:
 // callers own conversation history, which is what lets the same function
 // serve a one-shot CLI invocation and a long-lived chat session.
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parse as parseYaml } from 'yaml';
 import { Gate, RuleSet, ConsoleApprover } from 'actauth';
 import { SkillGarden } from 'skillgarden';
 import { ContextClipper } from 'contextclip';
 import { ToolLane } from 'toollane';
 import { Reflow } from 'reflowkit';
+import { loadAgentModule } from './discover-agents.js';
+import { agentAsTool } from './agent-as-tool.js';
+// Resolved relative to *this file's own location* (via import.meta.url),
+// not process.cwd() — the same reasoning agent-registry.ts's own
+// agentsDir uses. In dev (tsx), this file and agents/ are both source
+// .ts, side by side. In the built dist/, this file is dist/run-agent.js
+// and its sibling agents/ is dist/agents/**/*.js (tsc-compiled) — cwd is
+// irrelevant to either case, only "next to this module" is reliably
+// right in both. skillsDirs/rules don't need this: actauth.yml/SKILL.md
+// are plain data copied verbatim into the image (see Dockerfile), so
+// they exist at the same cwd-relative path either way; a tools/index.ts
+// is real code that only exists compiled, at a different relative
+// location, once dist/ is what's actually running.
+const agentsRootDir = join(dirname(fileURLToPath(import.meta.url)), 'agents');
 /** ContextClip only ever needs a flat string per message to estimate
  * token usage — it doesn't need to understand tool_use/tool_result
  * structure, so this is a one-way, read-only projection, never something
@@ -29,20 +47,215 @@ function flattenForContextClip(message) {
         .join('\n');
     return { role: message.role, content: text };
 }
+/** Parses a loopengine actauth.yml — same shape as examples/actauth.yml
+ * in the actauth package, except each rule's `scope` only needs
+ * tenant/environment (a wildcard/wildcard, wildcard/staging, or
+ * acme-corp/production pair, say) — the agent segment is appended
+ * automatically from AgentConfig.name, then handed to actauth's own
+ * RuleSet.fromRaw (not fromYamlFile, which
+ * expects the full 3-segment scope already baked into the file). A
+ * per-agent actauth.yml (this repo's own convention: one file, one
+ * agent, path derived from the agent's own name — see
+ * agents/customer-service/actauth.yml) can only ever describe rules for
+ * that one agent anyway, so repeating its name in every single rule is
+ * exactly the kind of boilerplate skillsDirs/rules/tools' own defaults
+ * already avoid elsewhere in this file. */
+function loadYamlRules(path, agentName) {
+    const raw = (parseYaml(readFileSync(path, 'utf8')) ?? {});
+    // A rule already ending in /<agentName> — the old, full 3-segment habit,
+    // or examples/actauth.yml copied verbatim — is left alone rather than
+    // getting a second, invalid segment appended; only the new 2-segment
+    // (tenant/environment) form actually needs the suffix.
+    const rules = (raw.rules ?? []).map((r) => ({
+        ...r,
+        scope: r.scope.endsWith(`/${agentName}`) ? r.scope : `${r.scope}/${agentName}`,
+    }));
+    return RuleSet.fromRaw({ default_decision: raw.default_decision, rules });
+}
+/** Resolves AgentConfig.rules the same way skillsDirs resolves its own
+ * default: an inline array is used as-is (full 3-segment scopePattern,
+ * unchanged — see loadYamlRules for why only the YAML form gets the
+ * agent segment auto-appended); omitted entirely defaults to
+ * `agents/<name>/actauth.yml`, this repo's own folder-form convention.
+ * Unlike skillsDirs, a missing *default* file falls back to an empty
+ * ruleset rather than propagating the raw ENOENT — permissions failing
+ * shouldn't crash the whole call. That fallback defaults to `'deny'`, not
+ * the inline-array form's `'ask'`: no `actauth.yml` at all means this
+ * agent's permission story was never actually written, which is a
+ * stricter unknown than "written, but this one tool has no rule" — 'ask'
+ * still runs an Approver that could auto-approve, while 'deny' refuses
+ * outright until real rules exist. `defaultDecision`, if set, still wins
+ * over that. An *explicitly* given path that doesn't exist is a real
+ * configuration bug, though, and still throws — only the silent, implicit
+ * default gets this forgiveness.
+ *
+ * Exported (alongside loadDefaultTools below) so adapters/http.ts's
+ * GET /agents/:name/config route can show the same rules runAgent() would
+ * actually enforce, not a re-derived guess at them. */
+export function loadRules(config) {
+    if (Array.isArray(config.rules))
+        return new RuleSet(config.rules, config.defaultDecision ?? 'ask');
+    const usingDefaultPath = config.rules === undefined;
+    const path = config.rules ?? `agents/${config.name}/actauth.yml`;
+    try {
+        return loadYamlRules(path, config.name);
+    }
+    catch (err) {
+        if (usingDefaultPath && err.code === 'ENOENT') {
+            return new RuleSet([], config.defaultDecision ?? 'deny');
+        }
+        throw err;
+    }
+}
+/** Resolves AgentConfig.tools the same way loadRules resolves its own
+ * default: an explicit array (including `[]`) is used as-is; omitted
+ * entirely defaults to importing `agents/<name>/tools/index.{ts,js}`
+ * (this repo's own aggregation-file convention — see
+ * `agents/customer-service/tools/index.ts`) and using its exported
+ * `tools`. A missing file there is not an error — a flat-file agent with
+ * no tools folder at all (or one merging in dynamically-loaded tools, like
+ * `agents/file-agent/index.ts`'s Composio ones, so it can't just rely on
+ * this default) just gets `[]`, same as if it had explicitly set that. A
+ * module that *does* exist but throws while importing, or doesn't export
+ * `tools` at all, is a real bug and is not swallowed. */
+async function loadToolsFromDir(toolsDir) {
+    for (const indexName of ['index.ts', 'index.js']) {
+        const indexPath = join(toolsDir, indexName);
+        if (!existsSync(indexPath))
+            continue;
+        const mod = (await import(pathToFileURL(indexPath).href));
+        if (!Array.isArray(mod.tools)) {
+            throw new Error(`${indexPath} does not export a 'tools' array — every agents/<name>/tools/index file must.`);
+        }
+        return mod.tools;
+    }
+    return [];
+}
+export async function loadDefaultTools(config) {
+    return loadToolsFromDir(join(agentsRootDir, config.name, 'tools'));
+}
+/** Every other folder-form default in this file (loadDefaultTools,
+ * loadRules, the skillsDirs default below) resolves against
+ * `agents/<name>/` — correct for a top-level agent, where that's exactly
+ * where its module lives, but wrong for a subagent: its `config` only
+ * carries its own bare name (e.g. 'billing-agent'), not the nested folder
+ * loadSubagentTools actually found it in
+ * (`agents/support-orchestrator/subagents/billing-agent/`). Left alone,
+ * an omitted `tools`/`rules`/`skillsDirs` on a subagent would silently
+ * resolve against `agents/billing-agent/...` instead — empty, if no such
+ * top-level folder exists, or worse, some *unrelated* top-level agent's
+ * tools/rules/skills, if one happens to share the same name.
+ *
+ * This patches exactly those three fields — only when the subagent's own
+ * config left them unset — to resolve against `dir`, its real folder,
+ * before it's ever handed to agentAsTool/runAgent. An explicit value on
+ * the subagent's own config (its author opted out on purpose) is always
+ * left untouched. `rules` gets the same "missing file is fine, empty
+ * deny-everything ruleset" fallback loadRules's own default path gets —
+ * computed here instead of left to loadRules, since leaving `rules`
+ * unset would have it fall through to loadRules's *own* (wrong,
+ * name-based) default path instead of this one. */
+async function resolveSubagentConfig(config, dir) {
+    const resolved = { ...config };
+    if (resolved.tools === undefined) {
+        resolved.tools = await loadToolsFromDir(join(dir, 'tools'));
+    }
+    if (resolved.rules === undefined) {
+        const rulesPath = join(dir, 'actauth.yml');
+        if (existsSync(rulesPath)) {
+            resolved.rules = rulesPath;
+        }
+        else {
+            resolved.rules = [];
+            resolved.defaultDecision = resolved.defaultDecision ?? 'deny';
+        }
+    }
+    if (resolved.skillsDirs === undefined) {
+        resolved.skillsDirs = [join(dir, 'skills')];
+    }
+    return resolved;
+}
+/** Auto-loads agents/<name>/subagents/<child>/index.{ts,js} — each one a
+ * full AgentConfig, wrapped with agentAsTool and merged into `config`'s
+ * own tools, no import or AgentConfig.tools edit required. Unlike
+ * loadDefaultTools, this always runs regardless of whether `config.tools`
+ * was left to its own default or set explicitly — see AgentConfig.tools's
+ * own doc comment for why subagents are a distinct concern from
+ * hand-written tools. A missing subagents/ folder is just `[]`, same
+ * missing-is-fine treatment tools/ and skills/ get; a subdirectory with
+ * neither index.ts nor index.js is skipped, same as resolveModulePath's
+ * own handling in discover-agents.ts.
+ *
+ * Each subagent is loaded via loadAgentModule — the same per-module
+ * resolution discoverAgents itself uses — then patched by
+ * resolveSubagentConfig (see its own doc comment for why) before being
+ * wrapped. Its own `config` goes through this exact same function again
+ * the next time *it* runs (inside agentAsTool's execute, via runAgent).
+ * That's what makes nesting (a subagent with its own subagents/ folder)
+ * work with no extra recursion code: it's just this function being
+ * called again, one level down. A folder can't be its own ancestor, so
+ * this can't cycle the way a hand-wired agentAsTool(getEntry(...)) call
+ * elsewhere could. */
+async function loadSubagentTools(config) {
+    const subagentsDir = join(agentsRootDir, config.name, 'subagents');
+    if (!existsSync(subagentsDir))
+        return [];
+    const tools = [];
+    for (const dirent of readdirSync(subagentsDir, { withFileTypes: true })) {
+        if (!dirent.isDirectory())
+            continue;
+        const dir = join(subagentsDir, dirent.name);
+        const indexPath = ['index.ts', 'index.js'].map((n) => join(dir, n)).find((p) => existsSync(p));
+        if (!indexPath)
+            continue;
+        const label = `agents/${config.name}/subagents/${dirent.name}/index`;
+        const subagent = await loadAgentModule(indexPath, label);
+        const subagentConfig = await resolveSubagentConfig(subagent.config, dir);
+        tools.push(agentAsTool(subagentConfig, subagent.createModelCall));
+    }
+    return tools;
+}
 export async function runAgent(config, modelCall, userMessage, history = [], options = {}) {
     const log = options.onEvent ?? (() => { });
-    const scope = { tenant: 'default', environment: 'production', ...config.scope, agent: config.name };
-    const skillGarden = config.skillsDirs?.length
-        ? new SkillGarden({ dirs: config.skillsDirs, indexBudgetTokens: config.skillIndexBudgetTokens ?? 200 })
-        : null;
+    // tenant: resolved by the caller (adapters/http.ts calls
+    // AgentConfig.tenantFor with the request's headers/body; every other
+    // caller — adapters/cli.ts, a standalone script — has no request to
+    // resolve it from, so it never passes this option and gets 'default').
+    // environment: a deployment-wide setting,
+    // not a per-agent or per-request one — always LOOPENGINE_ENV, same
+    // everywhere this process runs, never something an AgentConfig defines.
+    const scope = { tenant: options.tenant ?? 'default', environment: process.env.LOOPENGINE_ENV ?? 'production', agent: config.name };
+    // Optional on AgentConfig — an agent can have zero tools. Explicit
+    // (including `[]`) is used as-is; omitted entirely defaults to
+    // importing agents/<name>/tools/index.{ts,js} — see loadDefaultTools's
+    // own doc comment for the full reasoning and the cases that can't use it.
+    // agents/<name>/subagents/* is merged in on top either way — see
+    // loadSubagentTools's own doc comment for why that one isn't gated by
+    // whether `tools` was explicit.
+    const tools = [...(config.tools ?? (await loadDefaultTools(config))), ...(await loadSubagentTools(config))];
+    // Omitted entirely (undefined): default to this agent's own
+    // agents/<name>/skills — the folder-form convention every agent in
+    // this repo already follows (see agent-config.ts's skillsDirs doc
+    // comment). An explicit `[]` is a real opt-out, not "unset," and skips
+    // the default — SkillGarden's own missing-directory handling
+    // (discoverSkillFiles walks best-effort, no throw) is what makes
+    // pointing this at a folder that doesn't exist (a flat-file agent with
+    // no skills at all) harmless: an empty index, not an error.
+    const skillsDirs = config.skillsDirs ?? [`agents/${config.name}/skills`];
+    const skillGarden = skillsDirs.length ? new SkillGarden({ dirs: skillsDirs, indexBudgetTokens: config.skillIndexBudgetTokens ?? 200 }) : null;
     const skillIndex = skillGarden?.buildIndex().included ?? [];
     // Also the tail-preservation window recover() below relies on — kept as
     // one named constant so the two can never drift out of sync.
     const tailMessages = 4;
     const contextClip = new ContextClipper({ budgetTokens: config.contextBudgetTokens ?? 8000, tailMessages });
-    const rules = new RuleSet(config.rules, config.defaultDecision ?? 'ask');
+    const rules = loadRules(config);
     const gate = new Gate(rules, config.approver ?? new ConsoleApprover());
-    const toolLane = new ToolLane({ isSafe: config.isSafeTool ?? (() => false) });
+    // No explicit isSafeTool: fall back to each called tool's own `safe`
+    // flag (looked up by name) rather than defaulting every tool to unsafe
+    // outright — see ToolDefinition.safe's own doc comment for why this is
+    // the less powerful of the two (name-only, no per-call nuance).
+    const isSafeTool = config.isSafeTool ?? ((call) => tools.some((t) => t.name === call.name && t.safe === true));
+    const toolLane = new ToolLane({ isSafe: isSafeTool });
     let messages = [...history, { role: 'user', content: userMessage }];
     // Tracked in parallel with `messages`, but never rewritten wholesale by
     // recovery the way `messages` is — this is the actual, authoritative
@@ -93,8 +306,6 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
             return recovered;
         },
     });
-    // Optional on AgentConfig — an agent can have zero tools.
-    const tools = config.tools ?? [];
     const toolsByName = new Map(tools.map((t) => [t.name, t]));
     const toolSchemas = tools.map(({ name, description, input_schema }) => ({
         name,

package/dist/session-store.d.ts

@@ -1,6 +1,6 @@
 import { Redis } from 'ioredis';
 import { type Storage } from 'sessionknit';
-import type { Message } from './run-agent.js';
+import type { Message } from '#run-agent.js';
 export interface SessionResult<T> {
     /** Exactly what this turn added — durably appended as-is, in order.
      * This has to come from the caller explicitly (runAgent's own

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopengine",
-  "version": "0.0.10",
+  "version": "0.0.16",
   "type": "module",
   "description": "Runtime for tool-using AI agents with a transparent ReAct loop.",
   "license": "MIT",
@@ -11,9 +11,17 @@
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "loopengine": "dist/cli.js"
+  },
+  "imports": {
+    "#*": "./*"
+  },
   "files": [
     "dist/index.js",
     "dist/index.d.ts",
+    "dist/cli.js",
+    "dist/cli.d.ts",
     "dist/run-agent.js",
     "dist/run-agent.d.ts",
     "dist/agent-config.js",
@@ -22,18 +30,20 @@
     "dist/session-store.d.ts",
     "dist/vector-index.js",
     "dist/vector-index.d.ts",
-    "dist/anthropic-model-call.js",
-    "dist/anthropic-model-call.d.ts",
-    "dist/openai-model-call.js",
-    "dist/openai-model-call.d.ts",
-    "dist/deepseek-model-call.js",
-    "dist/deepseek-model-call.d.ts",
+    "dist/model-calls/anthropic-model-call.js",
+    "dist/model-calls/anthropic-model-call.d.ts",
+    "dist/model-calls/openai-model-call.js",
+    "dist/model-calls/openai-model-call.d.ts",
+    "dist/model-calls/deepseek-model-call.js",
+    "dist/model-calls/deepseek-model-call.d.ts",
     "dist/discover-agents.js",
     "dist/discover-agents.d.ts",
+    "dist/agent-as-tool.js",
+    "dist/agent-as-tool.d.ts",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && chmod +x dist/cli.js",
     "prepublishOnly": "npm run build",
     "start": "node dist/adapters/http.js",
     "test": "vitest run"
@@ -47,8 +57,9 @@
     "openai": "^7.4.0",
     "reflowkit": "^0.0.1",
     "sessionknit": "^0.0.2",
-    "skillgarden": "^0.0.4",
-    "toollane": "^0.0.1"
+    "skillgarden": "^0.0.5",
+    "toollane": "^0.0.1",
+    "yaml": "^2.6.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",