create-loopengine 0.1.8 → 0.1.11

package/template/agent-registry.ts

@@ -1,15 +1,20 @@
 // Every adapter resolves "which agent" through this — the thing that
-// makes agents pluggable. Defining a new agent means adding a file to
-// agents/ that exports `config` and `createModelCall` — nothing here or
-// in any adapter needs to change; discoverAgents scans that directory and
-// keys each entry by AgentConfig.name (not the filename) at import time.
+// makes agents pluggable. Defining a new agent means adding a file (or a
+// folder) to agents/ that exports `config` and `createModelCall` —
+// nothing here or in any adapter needs to change; discoverAgents scans
+// that directory and keys each entry by AgentConfig.name (not the
+// filename) at import time.
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { discoverAgents, type AgentModule } from 'loopengine'
+import { discoverAgents, type AgentConfig, type AgentModule, type ModelCall } from 'loopengine'
 
 export type RegistryEntry = AgentModule
 
-const agentsDir = join(dirname(fileURLToPath(import.meta.url)), 'agents')
+// This file lives at the project root, alongside agents/ — no '..' needed
+// (unlike loopengine's own core/agent-registry.ts, which lives nested one
+// level down in core/).
+const projectRoot = dirname(fileURLToPath(import.meta.url))
+const agentsDir = join(projectRoot, 'agents')
 
 // Top-level await: ESM guarantees an importer's own evaluation (adapters/
 // http.ts, adapters/cli.ts) waits for this module's top-level await to
@@ -25,3 +30,50 @@ export function listAgents(): string[] {
 export function getEntry(name: string): RegistryEntry | undefined {
   return entries.get(name)
 }
+
+/** Where this registry's own discoverAgents call resolved agents/
+ * against — exported so a caller creating a *new* agent module (the
+ * Admin UI's "Create new agent" flow, via loopengine's own scaffoldAgent)
+ * writes it to the exact same place this registry would find it on a
+ * future restart, rather than re-deriving a base dir independently (e.g.
+ * from process.cwd(), which isn't guaranteed to match if the process is
+ * launched from elsewhere) and risking the two drifting apart. */
+export function projectDir(): string {
+  return projectRoot
+}
+
+/** Adds one already-loaded agent module to the live registry in place —
+ * how a newly created agent becomes runnable in *this* process
+ * immediately, with no restart — unlike discoverAgents' own directory
+ * scan, which only ever runs once, at this module's own import time (see
+ * the top-level await above). Throws on a name collision with an
+ * already-registered agent, same as discoverAgents itself does for a
+ * collision found during its initial scan — a duplicate AgentConfig.name
+ * is a bug either way, not something to silently overwrite. */
+export function registerAgent(agentModule: RegistryEntry): void {
+  const name = agentModule.config.name
+  if (entries.has(name)) {
+    throw new Error(`Duplicate agent name '${name}' — an agent with this name is already registered.`)
+  }
+  entries.set(name, agentModule)
+}
+
+/** Applies a partial update to an already-registered agent — how an edit
+ * made through the Admin UI takes effect in *this* running process
+ * immediately, the same "no restart needed" principle gateway-tools.yml/
+ * actauth.yml/SKILL.md edits already have. Mutates the same AgentConfig
+ * object every existing getEntry() caller already holds a reference to —
+ * via Object.assign, not a full replacement — so nothing needs to
+ * re-fetch it to see the change, and any field left out of `patch.config`
+ * (tools, rules, skillsDirs, ...) stays exactly as it was.
+ * `patch.createModelCall`, if given, replaces the cached one wholesale.
+ * Throws if `name` isn't already registered — this updates an existing
+ * entry, it's not a back door around registerAgent's own creation path. */
+export function updateAgent(name: string, patch: { config?: Partial<AgentConfig>; createModelCall?: () => ModelCall }): void {
+  const entry = entries.get(name)
+  if (!entry) {
+    throw new Error(`No registered agent named '${name}' to update.`)
+  }
+  if (patch.config) Object.assign(entry.config, patch.config)
+  if (patch.createModelCall) entry.createModelCall = patch.createModelCall
+}

package/template/agents/example-agent/actauth.yml

@@ -0,0 +1,12 @@
+# The permission story for this agent: which tool, which rule, allow or
+# ask. Loaded automatically because index.ts doesn't set `rules` itself —
+# omitting it defaults to this file, agents/<name>/actauth.yml, resolved
+# from wherever you run the process (see AgentConfig.rules's own doc
+# comment in loopengine for the full resolution rules).
+default_decision: ask
+
+rules:
+  - name: get-weather-always-allowed
+    scope: "*/*"
+    tool: get_weather
+    decision: allow

package/template/agents/example-agent/index.ts

@@ -0,0 +1,29 @@
+// A starting point, not a template to copy verbatim: real persona, real
+// tool, real permission rule — one folder per agent, the same convention
+// agents/customer-service/ uses in loopengine's own repo. Add more agents
+// by copying this whole folder under a new name and a new AgentConfig.name
+// — agent-registry.ts discovers it automatically, nothing to register by
+// hand.
+//
+// `rules` and `skillsDirs` are both left unset here on purpose — omitting
+// them defaults to actauth.yml and skills/ alongside this file (loopengine
+// resolves both relative to wherever you run the process). `tools` is set
+// explicitly instead of relying on the equivalent tools/ default: that one
+// resolves relative to loopengine's own installed location, not your
+// project, so it only works inside loopengine's own repo — see
+// tools/index.ts's own comment.
+import { createAnthropicModelCall, type AgentConfig, type ModelCall } from 'loopengine'
+import { tools } from './tools/index.js'
+
+export const config: AgentConfig = {
+  name: 'example-agent',
+  systemPrompt: 'You are a helpful assistant.',
+  tools,
+}
+
+// Reads ANTHROPIC_API_KEY from the env. Swap for
+// createOpenAIModelCall({ model: '...' }) to use OpenAI instead — see
+// node_modules/loopengine/README.md's "Wiring a real model" section.
+export function createModelCall(): ModelCall {
+  return createAnthropicModelCall({ model: 'claude-sonnet-5' })
+}

package/template/agents/example-agent/skills/convert-temperature/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: convert-temperature
+description: Convert a temperature between Celsius and Fahrenheit without a tool call.
+---
+
+# Convert temperature
+
+To convert Celsius to Fahrenheit: multiply by 9/5, then add 32.
+To convert Fahrenheit to Celsius: subtract 32, then multiply by 5/9.
+
+Do the arithmetic yourself and show the result — no tool needed for this.

package/template/agents/example-agent/tools/get_weather.ts

@@ -0,0 +1,8 @@
+import type { ToolDefinition } from 'loopengine'
+
+export const getWeather: ToolDefinition = {
+  name: 'get_weather',
+  description: 'Look up the weather for a city',
+  input_schema: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] },
+  execute: async (input) => `Sunny in ${input.city}`,
+}

package/template/agents/example-agent/tools/index.ts

@@ -0,0 +1,12 @@
+// Aggregates this agent's tools — one file per tool, so adding another
+// tool later means adding a file here and one line below, not touching
+// index.ts. Mirrors loopengine's own agents/customer-service/tools/index.ts,
+// except index.ts here imports this file explicitly (`tools,` in its
+// AgentConfig) rather than omitting `tools` and relying on loopengine's
+// own auto-import of this exact path: that default is resolved relative
+// to loopengine's own installed location, so it only finds a tools/
+// folder that lives inside loopengine's own repo, not your project's.
+import type { ToolDefinition } from 'loopengine'
+import { getWeather } from './get_weather.js'
+
+export const tools: ToolDefinition[] = [getWeather]

package/template/package.json

@@ -9,7 +9,9 @@
     "cli": "tsx adapters/cli.ts"
   },
   "dependencies": {
-    "loopengine": "^0.1.2"
+    "loopengine": "^0.1.4",
+    "actauth": "^0.0.12",
+    "skillgarden": "^0.0.5"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

package/template/agents/example-agent.ts

@@ -1,27 +0,0 @@
-// A starting point, not a template to copy verbatim: real persona, real
-// tool, real permission rule. Add more agents by copying this file into
-// agents/ under a new filename and a new AgentConfig.name — agent-registry.ts
-// discovers it automatically, nothing to register by hand.
-import { createAnthropicModelCall, type AgentConfig, type ModelCall } from 'loopengine'
-
-export const config: AgentConfig = {
-  name: 'example-agent',
-  systemPrompt: 'You are a helpful assistant.',
-  tools: [
-    {
-      name: 'get_weather',
-      description: 'Look up the weather for a city',
-      input_schema: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] },
-      execute: async (input) => `Sunny in ${input.city}`,
-    },
-  ],
-  rules: [{ scopePattern: 'default/production/example-agent', tool: 'get_weather', decision: 'allow' }],
-  defaultDecision: 'ask',
-}
-
-// Reads ANTHROPIC_API_KEY from the env. Swap for
-// createOpenAIModelCall({ model: '...' }) to use OpenAI instead — see
-// node_modules/loopengine/README.md's "Wiring a real model" section.
-export function createModelCall(): ModelCall {
-  return createAnthropicModelCall({ model: 'claude-sonnet-5' })
-}