loopengine 0.0.10 → 0.0.14

package/dist/agent-config.d.ts

@@ -1,5 +1,36 @@
-import type { Rule, Decision, Scope, Approver } from 'actauth';
+import type { Rule, Decision, Approver } from 'actauth';
 import type { SafetyClassifier } from 'toollane';
+/** Declares which real ModelCall an agent module wants built for it, so
+ * the module doesn't have to export its own `createModelCall` —
+ * `discoverAgents` synthesizes one instead (see `discover-agents.ts`),
+ * lazily and memoized, the same pattern
+ * `agents/customer-service/index.ts`'s own hand-written `createModelCall`
+ * used before this existed. Each provider's own `createXModelCall`
+ * factory (`model-calls/*.ts`) still exists and still works standalone —
+ * this is a convenience for the common case, not a replacement; still
+ * export your own `createModelCall` for anything this can't express (a
+ * canned/simulated `ModelCall` for a demo, a custom SDK client, a
+ * provider this doesn't list). `model` is required for `openai`/
+ * `deepseek` (no safe hardcoded default — a flagship model name changes
+ * too often to bake one in) but optional for `anthropic` (defaults to
+ * `'claude-sonnet-5'`), mirroring each factory's own options exactly. */
+export type AgentModelConfig = {
+    provider: 'anthropic';
+    model?: string;
+    apiKey?: string;
+    maxTokens?: number;
+} | {
+    provider: 'openai';
+    model: string;
+    apiKey?: string;
+    maxTokens?: number;
+} | {
+    provider: 'deepseek';
+    model: string;
+    apiKey?: string;
+    maxTokens?: number;
+    baseURL?: string;
+};
 export interface ToolSchema {
     name: string;
     description: string;
@@ -8,21 +39,89 @@ export interface ToolSchema {
 }
 export interface ToolDefinition extends ToolSchema {
     execute: (input: Record<string, unknown>) => Promise<unknown>;
+    /** Safe to run in ToolLane's parallel lane alongside other safe calls —
+     * true for a read-only tool with no side effects and no shared mutable
+     * state (a lookup, a search), false/omitted for anything that mutates
+     * something (a refund, an email, a write). Only consulted as a default
+     * when `AgentConfig.isSafeTool` isn't set — see that field's own doc
+     * comment for why a classifier function (call-level, agent-level) is
+     * the more powerful of the two and takes full precedence when given. */
+    safe?: boolean;
 }
 export interface AgentConfig {
     /** Also doubles as the ActAuth scope.agent segment. */
     name: string;
     systemPrompt: string;
-    /** Hand-written tools. Default []. */
+    /** See AgentModelConfig's own doc comment. Omit entirely and the module
+     * must export its own `createModelCall` instead — `discoverAgents`
+     * throws at startup on a module with neither. */
+    model?: AgentModelConfig;
+    /** Hand-written tools. An explicit array (including `[]`) is used as-is.
+     * Omit entirely and it defaults to importing
+     * `agents/<name>/tools/index.{ts,js}` and using its exported `tools` —
+     * this repo's own aggregation-file convention (see
+     * `agents/customer-service/tools/index.ts`), resolved next to
+     * `run-agent.ts` itself (not `process.cwd()`, unlike `skillsDirs`/
+     * `rules` — that file is real compiled code, not data, so it has to be
+     * found next to whichever build of `run-agent.ts` is actually running).
+     * A missing file there is just `[]`, not an error — same
+     * missing-is-fine treatment `skillsDirs` gets. An agent that needs to
+     * merge in tools from somewhere else too (e.g.
+     * `agents/file-agent/index.ts`'s Composio-sourced ones) can't rely on
+     * this default and still needs to set `tools` explicitly. */
     tools?: ToolDefinition[];
-    /** ActAuth rules, e.g. { scopePattern: 'default/production/customer-service', tool: 'issue_refund', decision: 'ask' } */
-    rules: Rule[];
-    /** Decision when no rule matches. Default 'ask' — new tools are opt-in, not silently allowed. */
+    /** ActAuth rules — either inline (handy for tests and small/synthetic
+     * configs) or a path to an `actauth.yml` file (same shape as
+     * `examples/actauth.yml` in the actauth package: top-level
+     * `default_decision` + a `rules:` list with `scope`/`tool`/`decision`/
+     * optional `when`), resolved against `process.cwd()` the same way
+     * `skillsDirs` is. A real agent with more than a couple of rules should
+     * use the file form — see agents/customer-service/actauth.yml — since a
+     * permission story with `when` conditions and per-tenant/environment
+     * scoping reads better as data than as a TypeScript array literal.
+     * `defaultDecision` below only applies to the inline-array form; the
+     * file form carries its own `default_decision` and ignores it.
+     *
+     * Omit entirely and it defaults to `agents/<name>/actauth.yml` — same
+     * folder-form convention `skillsDirs` defaults to. Unlike `skillsDirs`,
+     * a missing file there doesn't silently mean "no rules apply" as if
+     * every tool were pre-approved — it falls back to an empty ruleset
+     * governed by `defaultDecision` (default `'deny'` here, stricter than
+     * the inline-array form's `'ask'` default: no file at all means this
+     * agent's permission story was never written, not just incomplete), so
+     * an agent with no `actauth.yml` yet refuses every tool outright,
+     * rather than either crashing or silently allowing/asking. */
+    rules?: Rule[] | string;
+    /** Decision when no rule matches, for the inline-array `rules` form only.
+     * Default 'ask' — new tools are opt-in, not silently allowed. */
     defaultDecision?: Decision;
     /** Default ConsoleApprover (blocks on stdin) — pass e.g. a Slack-backed Approver for unattended agents. */
     approver?: Approver;
-    scope?: Partial<Omit<Scope, 'agent'>>;
-    /** SKILL.md directories this agent can discover and invoke. Omit if the agent has no skills. */
+    /** Resolves the ActAuth tenant for a request, from headers (never the
+     * body: tenant feeds permission decisions directly, so it has to come
+     * from something verified — an Authorization/API-key header checked
+     * against your own mapping — never a raw client-asserted body field
+     * that would let any caller claim to be any tenant and inherit that
+     * tenant's rules). Only `adapters/http.ts` can actually call this (it
+     * alone has a request's headers to call it with) — `run-agent.ts`
+     * itself never sees a request, so `runAgent()`'s standalone/CLI callers
+     * always get the `'default'` tenant, the same as omitting this field
+     * entirely. Returning `undefined` is a real auth failure
+     * (`adapters/http.ts` responds `401`), not "fall back to `'default'`"
+     * — if "no header at all" should resolve to `'default'` rather than a
+     * rejection, the resolver itself must return `'default'` explicitly.
+     *
+     * There's no equivalent `environment` field: environment is a
+     * deployment-wide setting (`LOOPENGINE_ENV`, default `'production'`),
+     * not something that varies by agent or by request. */
+    tenantFor?: (headers: Record<string, string | string[] | undefined>, body: Record<string, unknown>) => string | undefined;
+    /** SKILL.md directories this agent can discover and invoke, resolved
+     * against `process.cwd()` (not this config's own file location). Omit
+     * entirely and it defaults to `agents/<name>/skills` — this repo's own
+     * folder-form convention (see `agents/customer-service/skills/`) — which
+     * is harmless even if that folder doesn't exist (a flat-file agent with
+     * no skills at all just gets an empty index, not an error). Pass `[]`
+     * explicitly instead of omitting the field to opt out of that default. */
     skillsDirs?: string[];
     skillIndexBudgetTokens?: number;
     contextBudgetTokens?: number;
@@ -34,7 +133,13 @@ export interface AgentConfig {
      * RunAgentResult.stopReason set to 'max_turns' so a caller can tell the
      * difference from a normal finish. */
     maxTurns?: number;
-    /** Which tools ToolLane may run in a parallel lane. Default: none (every tool runs solo). */
+    /** Which tools ToolLane may run in a parallel lane. Takes full
+     * precedence over each tool's own `ToolDefinition.safe` flag when set —
+     * it's strictly more powerful (a function of the whole call, not just
+     * the tool's static definition, so it can vary by agent or, if you
+     * thread args through, by the call's own input). Omit it to fall back
+     * to each called tool's own `safe` flag instead (looked up by name);
+     * omit both and every tool runs solo. */
     isSafeTool?: SafetyClassifier;
     /** How adapters/http.ts derives a session key from a request body — this
      * is business logic ("what counts as one conversation" is agent-
@@ -43,6 +148,15 @@ export interface AgentConfig {
      * adapter. Return undefined to signal "this body doesn't identify a
      * session" (the adapter responds 400). Omit entirely to use the
      * adapter's default — a client-supplied `sessionId` field, the same
-     * shape adapters/cli.ts's --session flag already uses. */
+     * shape adapters/cli.ts's --session flag already uses.
+     *
+     * Body-only, unlike `tenantFor` above — a spoofed session key only lets
+     * someone read/continue the wrong *conversation*; it doesn't grant
+     * elevated tool permissions the way a spoofed tenant would. Real
+     * verified-identity session keys (deriving this from an auth header
+     * instead of a client-asserted body field like customerEmail) are a
+     * legitimate future need, but nothing in this repo has a concrete use
+     * for it yet — no sense widening this signature speculatively before
+     * there's a real consumer to shape it around. */
     sessionIdFor?: (body: Record<string, unknown>) => string | undefined;
 }

package/dist/discover-agents.d.ts

@@ -5,12 +5,11 @@ export interface AgentModule {
     /** Factory, not a shared instance — a fresh ModelCall per request/session. */
     createModelCall: () => ModelCall;
 }
-/** Scans `dir`'s direct files only (not subdirectories — put shared,
- * non-agent code in a subdirectory to keep it out of discovery, no
- * separate exclude-list mechanism needed) for `.ts`/`.js` modules, each
- * expected to export `config` and `createModelCall` — the same shape
- * every agents/*.ts file in this repo's own reference app already
- * exports. Throws, rather than skipping, on a file that doesn't match
- * that shape or a duplicate AgentConfig.name — both are almost always a
- * bug in the agent file, not something to silently ignore. */
+/** Scans `dir` for agent modules — direct `.ts`/`.js` files, or
+ * subdirectories with an `index.ts`/`index.js` (see resolveModulePath) —
+ * each expected to export `config`, and either its own `createModelCall`
+ * or a `config.model` for one to be synthesized from (see
+ * AgentModelConfig's own doc comment). Throws, rather than skipping, on a
+ * module that doesn't match that shape or a duplicate AgentConfig.name —
+ * both are almost always a bug, not something to silently ignore. */
 export declare function discoverAgents(dir: string): Promise<Map<string, AgentModule>>;

package/dist/discover-agents.js

@@ -11,38 +11,87 @@
 // silently collide in ActAuth's rules today regardless of this helper;
 // surfacing that collision loudly here, at discovery time, is a real
 // safety property this adds, not just convenience.
-import { readdirSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { existsSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-function isAgentModule(mod) {
-    return (typeof mod === 'object' &&
-        mod !== null &&
-        'config' in mod &&
-        'createModelCall' in mod &&
-        typeof mod.createModelCall === 'function');
+function isRawAgentModule(mod) {
+    return typeof mod === 'object' && mod !== null && 'config' in mod;
 }
-/** Scans `dir`'s direct files only (not subdirectories — put shared,
- * non-agent code in a subdirectory to keep it out of discovery, no
- * separate exclude-list mechanism needed) for `.ts`/`.js` modules, each
- * expected to export `config` and `createModelCall` — the same shape
- * every agents/*.ts file in this repo's own reference app already
- * exports. Throws, rather than skipping, on a file that doesn't match
- * that shape or a duplicate AgentConfig.name — both are almost always a
- * bug in the agent file, not something to silently ignore. */
+/** Builds a lazy, memoized createModelCall from AgentConfig.model, for a
+ * module that doesn't export its own — see that field's own doc comment.
+ * The provider's SDK module is imported here, eagerly, but that's cheap
+ * and safe with no API key at all: importing model-calls/*.ts only
+ * defines functions, it never constructs a client at module top level
+ * (see e.g. createAnthropicModelCall's own body) — so this can't fail
+ * discovery the way eagerly building the actual client would. The real
+ * client is only built the first time the returned function is actually
+ * called, and reused after that, the same "don't crash the whole server
+ * over one agent's missing API key, don't rebuild per call" reasoning
+ * agents/customer-service/index.ts's own hand-written createModelCall
+ * used before this existed. */
+async function synthesizeCreateModelCall(model) {
+    let cached;
+    if (model.provider === 'anthropic') {
+        const { createAnthropicModelCall } = await import('./model-calls/anthropic-model-call.js');
+        return () => (cached ??= createAnthropicModelCall(model));
+    }
+    if (model.provider === 'openai') {
+        const { createOpenAIModelCall } = await import('./model-calls/openai-model-call.js');
+        return () => (cached ??= createOpenAIModelCall(model));
+    }
+    const { createDeepSeekModelCall } = await import('./model-calls/deepseek-model-call.js');
+    return () => (cached ??= createDeepSeekModelCall(model));
+}
+/** Resolves one directory entry to an agent module's path, or undefined if
+ * this entry isn't one — a `.ts`/`.js` file directly (the common case), or
+ * a subdirectory containing an `index.ts`/`index.js` (the same "a
+ * directory can be a module" convention Node's own `require()` resolution
+ * already uses — no new mental model to learn). A subdirectory with
+ * neither is ordinary supporting code living alongside an agent's own
+ * folder (a `tools.ts` split out of a large agent, say), not an agent
+ * itself, and is silently skipped rather than treated as an error. */
+function resolveModulePath(dir, entry) {
+    if (entry.isFile() && /\.(ts|js)$/.test(entry.name) && !entry.name.endsWith('.d.ts')) {
+        return { path: resolve(dir, entry.name), label: entry.name };
+    }
+    if (entry.isDirectory()) {
+        for (const indexName of ['index.ts', 'index.js']) {
+            const indexPath = join(dir, entry.name, indexName);
+            if (existsSync(indexPath))
+                return { path: resolve(indexPath), label: `${entry.name}/${indexName}` };
+        }
+    }
+    return undefined;
+}
+/** Scans `dir` for agent modules — direct `.ts`/`.js` files, or
+ * subdirectories with an `index.ts`/`index.js` (see resolveModulePath) —
+ * each expected to export `config`, and either its own `createModelCall`
+ * or a `config.model` for one to be synthesized from (see
+ * AgentModelConfig's own doc comment). Throws, rather than skipping, on a
+ * module that doesn't match that shape or a duplicate AgentConfig.name —
+ * both are almost always a bug, not something to silently ignore. */
 export async function discoverAgents(dir) {
     const entries = new Map();
-    const files = readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isFile() && /\.(ts|js)$/.test(entry.name) && !entry.name.endsWith('.d.ts'));
-    for (const file of files) {
-        const modulePath = resolve(dir, file.name);
-        const mod = await import(pathToFileURL(modulePath).href);
-        if (!isAgentModule(mod)) {
-            throw new Error(`${file.name} in ${dir} does not export both 'config' and 'createModelCall' — every agent module must.`);
+    for (const dirent of readdirSync(dir, { withFileTypes: true })) {
+        const resolved = resolveModulePath(dir, dirent);
+        if (!resolved)
+            continue;
+        const mod = await import(pathToFileURL(resolved.path).href);
+        if (!isRawAgentModule(mod) || !mod.config) {
+            throw new Error(`${resolved.label} in ${dir} does not export 'config' — every agent module must.`);
+        }
+        let createModelCall = mod.createModelCall;
+        if (typeof createModelCall !== 'function') {
+            if (!mod.config.model) {
+                throw new Error(`${resolved.label} in ${dir} exports 'config' but neither 'createModelCall' nor 'config.model' — every agent module must have one or the other.`);
+            }
+            createModelCall = await synthesizeCreateModelCall(mod.config.model);
         }
         const name = mod.config.name;
         if (entries.has(name)) {
-            throw new Error(`Duplicate agent name '${name}' — ${file.name} in ${dir} isn't the first file to declare AgentConfig.name '${name}'.`);
+            throw new Error(`Duplicate agent name '${name}' — ${resolved.label} in ${dir} isn't the first module to declare AgentConfig.name '${name}'.`);
         }
-        entries.set(name, mod);
+        entries.set(name, { config: mod.config, createModelCall });
     }
     return entries;
 }

package/dist/index.d.ts

@@ -1,15 +1,15 @@
 export { runAgent } from './run-agent.js';
 export type { Message, ModelCall, ModelContentBlock, ModelResponse, RunAgentOptions, RunAgentResult, } from './run-agent.js';
-export type { AgentConfig, ToolSchema, ToolDefinition } from './agent-config.js';
+export type { AgentConfig, AgentModelConfig, ToolSchema, ToolDefinition } from './agent-config.js';
 export { FileSessionStore, RedisSessionStore, createSessionStore } from './session-store.js';
 export type { SessionStore, SessionResult, RedisSessionStoreOptions } from './session-store.js';
 export { VectorIndex, embed, cosineSimilarity } from './vector-index.js';
 export type { Document, ScoredDocument } from './vector-index.js';
-export { createAnthropicModelCall } from './anthropic-model-call.js';
-export type { AnthropicModelCallOptions } from './anthropic-model-call.js';
-export { createOpenAIModelCall } from './openai-model-call.js';
-export type { OpenAIModelCallOptions } from './openai-model-call.js';
-export { createDeepSeekModelCall } from './deepseek-model-call.js';
-export type { DeepSeekModelCallOptions } from './deepseek-model-call.js';
+export { createAnthropicModelCall } from './model-calls/anthropic-model-call.js';
+export type { AnthropicModelCallOptions } from './model-calls/anthropic-model-call.js';
+export { createOpenAIModelCall } from './model-calls/openai-model-call.js';
+export type { OpenAIModelCallOptions } from './model-calls/openai-model-call.js';
+export { createDeepSeekModelCall } from './model-calls/deepseek-model-call.js';
+export type { DeepSeekModelCallOptions } from './model-calls/deepseek-model-call.js';
 export { discoverAgents } from './discover-agents.js';
 export type { AgentModule } from './discover-agents.js';

package/dist/index.js

@@ -6,7 +6,7 @@
 export { runAgent } from './run-agent.js';
 export { FileSessionStore, RedisSessionStore, createSessionStore } from './session-store.js';
 export { VectorIndex, embed, cosineSimilarity } from './vector-index.js';
-export { createAnthropicModelCall } from './anthropic-model-call.js';
-export { createOpenAIModelCall } from './openai-model-call.js';
-export { createDeepSeekModelCall } from './deepseek-model-call.js';
+export { createAnthropicModelCall } from './model-calls/anthropic-model-call.js';
+export { createOpenAIModelCall } from './model-calls/openai-model-call.js';
+export { createDeepSeekModelCall } from './model-calls/deepseek-model-call.js';
 export { discoverAgents } from './discover-agents.js';

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

@@ -38,6 +38,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. */

package/dist/run-agent.js

@@ -3,11 +3,27 @@
 // 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 } 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';
+// 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 +45,125 @@ 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. */
+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 loadDefaultTools(config) {
+    const toolsDir = join(agentsRootDir, config.name, 'tools');
+    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 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.
+    const tools = config.tools ?? (await loadDefaultTools(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 +214,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopengine",
-  "version": "0.0.10",
+  "version": "0.0.14",
   "type": "module",
   "description": "Runtime for tool-using AI agents with a transparent ReAct loop.",
   "license": "MIT",
@@ -22,12 +22,12 @@
     "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",
     "LICENSE"
@@ -47,8 +47,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",