create-loopengine 0.1.8 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-loopengine",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Scaffold a new loopengine agent project — a runnable HTTP server with one example agent, in your own repo.",
   "license": "MIT",
   "type": "module",

package/template/README.md

@@ -33,24 +33,31 @@ npm run cli -- --agent example-agent "what is the weather in Boston?"
 
 ## Add another agent
 
-1. Copy `agents/example-agent.ts` to `agents/your-agent.ts` and edit its
-   `name`, `systemPrompt`, `tools`, and `rules`.
-2. That's it — `agent-registry.ts` discovers it automatically by
+1. Copy `agents/example-agent/` to `agents/your-agent/` — `index.ts`
+   (persona + which tools), `tools/` (one file per tool), `actauth.yml`
+   (the permission story), and `skills/` if it needs any.
+2. Edit `index.ts`'s `name` and `systemPrompt`, and `tools/index.ts`'s
+   tool list. `rules`/`skillsDirs` don't need touching — they're left
+   unset in `index.ts` on purpose, so they keep defaulting to
+   `actauth.yml`/`skills/` next to it.
+3. That's it — `agent-registry.ts` discovers it automatically by
    `AgentConfig.name`, no registration step. Nothing to edit, no import to
    add, no adapter change.
-3. Call it at `/agents/your-agent/messages`.
+4. Call it at `/agents/your-agent/messages`.
 
-A flat file like this is enough for most agents. An agent can also be a
-*folder* — `agents/your-agent/index.ts` instead of `agents/your-agent.ts`
-— which unlocks per-agent `tools/`, `skills/`, and `actauth.yml` defaults,
-and lets it have its own subagents (see below). `loopengine`'s own CLI
-scaffolds that folder form for you:
+`loopengine`'s own CLI scaffolds this same folder shape for you, if you'd
+rather start empty than copy `example-agent/`:
 
 ```bash
 npx loopengine add-agent your-agent
 # -> Created agents/your-agent/index.ts
 ```
 
+An agent can also be a single flat file — `agents/your-agent.ts` instead
+of a folder — if it's simple enough not to need its own `tools/`,
+`skills/`, or `actauth.yml`. It just can't have subagents (see below),
+since there's no folder for `subagents/` to live under.
+
 ## Composing agents (subagents)
 
 An agent's tools can be other agents. Drop a folder under
@@ -77,10 +84,13 @@ reaching for this.
 ## Project layout
 
 ```
-agent-registry.ts       Auto-discovers agents/*.ts by AgentConfig.name — nothing to edit here
-agents/example-agent.ts Starter agent: persona, one tool, one permission rule
-adapters/http.ts         HTTP API (streaming + non-streaming)
-adapters/cli.ts          Command-line adapter
+agent-registry.ts                Auto-discovers agents/* by AgentConfig.name — nothing to edit here
+agents/example-agent/index.ts    Starter agent: persona, one tool
+agents/example-agent/tools/      One tool (get_weather), aggregated in tools/index.ts
+agents/example-agent/actauth.yml One permission rule (allow get_weather), default_decision: ask
+agents/example-agent/skills/     One skill (convert-temperature) — instructions, not a tool call
+adapters/http.ts                  HTTP API (streaming + non-streaming)
+adapters/cli.ts                   Command-line adapter
 ```
 
 ## Adding external tools via Composio

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,7 @@
     "cli": "tsx adapters/cli.ts"
   },
   "dependencies": {
-    "loopengine": "^0.1.2"
+    "loopengine": "^0.1.3"
   },
   "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' })
-}