create-loopengine 0.1.8 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-loopengine",
-  "version": "0.1.8",
+  "version": "0.1.11",
   "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/.env.example

@@ -1,6 +1,6 @@
 ANTHROPIC_API_KEY=
-# Using OpenAI instead? Swap agents/example-agent.ts's createModelCall for
-# createOpenAIModelCall({ model: '...' }) and set this instead:
+# Using OpenAI instead? Swap agents/example-agent/index.ts's createModelCall
+# for createOpenAIModelCall({ model: '...' }) and set this instead:
 # OPENAI_API_KEY=
 
 PORT=8787
@@ -8,3 +8,9 @@ PORT=8787
 # Optional — omit for local, file-based sessions under .sessions/. Set this
 # once you run more than one server instance against the same sessions.
 # REDIS_URL=redis://localhost:6379
+
+# Optional, but set this before deploying anywhere reachable by anyone but
+# you: without it, every route on this server — including each agent's
+# conversation history — is wide open to anyone who can reach it.
+# "user:pass" turns on HTTP Basic Auth for all of them.
+# LOOPENGINE_ADMIN_AUTH=user:pass

package/template/README.md

@@ -31,26 +31,50 @@ Or from the command line directly, no server needed:
 npm run cli -- --agent example-agent "what is the weather in Boston?"
 ```
 
+## Admin UI
+
+`npm run dev`, then open:
+
+- `http://localhost:8787/agents/config` — create agents, edit system
+  prompts and models, connect Composio tool sources, and manage each
+  agent's permission rules and skills, all from the browser. "Create new
+  agent" writes a real folder under `agents/` and registers it live, no
+  restart needed.
+- `http://localhost:8787/playground` — send a real message to any agent
+  and watch its tool calls and permission decisions happen live, approve
+  or deny a gated call right there.
+
+Both are wide open by default (local-only convenience) — set
+`LOOPENGINE_ADMIN_AUTH="user:pass"` in `.env` before deploying anywhere
+reachable by anyone but you (see `.env.example`).
+
 ## 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 +101,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/adapters/cli.ts

@@ -3,51 +3,110 @@
 //
 //   npm run cli -- --agent example-agent "what's the weather in Boston?"
 //
-// Omit --session for a one-off ask — each call gets its own fresh,
+// Omit --session for a one-off ask — each such call gets its own fresh,
 // isolated session (a random id, printed to stderr so it can be reused
-// with --session <id> later to continue that conversation).
+// with --session <id> later if you want to continue that exact
+// conversation). Pass --session explicitly to have two calls share one
+// ongoing conversation on purpose.
+//
+//   npm run cli -- --agent example-agent --json "what's the weather in Boston?"
+//
+// --json prints the same typed LoopEvent stream adapters/http.ts's SSE
+// route sends as one JSON object per line on stdout, ending with a
+// 'done'/'error' event — nothing human-readable mixed in, so it's
+// pipeable straight into `jq` or another process. Without --json, stdout
+// stays human-oriented (just the final answer text) and events go to
+// stderr as a one-line summary each.
+//
+// Owns: parsing argv, loading/saving this session's history, printing the
+// result to stdout. Everything else is runAgent. Uses REDIS_URL if set
+// (see loopengine's own createSessionStore), a local .sessions/ dir
+// otherwise — either way, safe for concurrent invocations against the
+// same --session.
 import { randomUUID } from 'node:crypto'
-import { createSessionStore, runAgent } from 'loopengine'
+import { createSessionStore, runAgent, type LoopEvent } from 'loopengine'
 import { getEntry, listAgents } from '../agent-registry.js'
 
 function parseArgs(argv: string[]) {
   let agent = ''
   let session: string | undefined
+  let json = false
   const rest: string[] = []
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--agent') agent = argv[++i]
     else if (argv[i] === '--session') session = argv[++i]
+    else if (argv[i] === '--json') json = true
     else rest.push(argv[i])
   }
-  return { agent, session, message: rest.join(' ') }
+  return { agent, session, json, message: rest.join(' ') }
+}
+
+/** One NDJSON line per event — see this file's own header comment for
+ * why --json mode never mixes human-readable text into stdout. */
+function printJsonEvent(event: LoopEvent): void {
+  console.log(JSON.stringify(event))
 }
 
 async function main() {
-  const { agent, session, message } = parseArgs(process.argv.slice(2))
+  const { agent, session, json, message } = parseArgs(process.argv.slice(2))
   const entry = getEntry(agent)
   if (!entry) {
     console.error(`unknown agent '${agent}'. available: ${listAgents().join(', ')}`)
     process.exit(1)
   }
   if (!message) {
-    console.error('usage: cli.ts --agent <name> [--session <id>] "<message>"')
+    console.error('usage: cli.ts --agent <name> [--session <id>] [--json] "<message>"')
     process.exit(1)
   }
 
+  // No --session means "a fresh, one-off ask," not "join whatever the
+  // default conversation happens to be" — a shared 'default' bucket would
+  // silently accumulate history across every untagged invocation forever,
+  // splicing unrelated one-off asks into a single ever-growing session.
   const sessionId = session ?? randomUUID()
-  if (!session) console.error(`[session] ${sessionId} (pass --session ${sessionId} to continue this conversation)`)
+  // In --json mode this is the stream's own first line (mirroring
+  // adapters/http.ts's SSE 'session' event) — not also duplicated to
+  // stderr, so a consumer piping stdout gets exactly one place to learn
+  // the generated id from, same as an SSE client does.
+  if (json) printJsonEvent({ type: 'session', sessionId })
+  else if (!session) console.error(`[session] ${sessionId} (pass --session ${sessionId} to continue this conversation)`)
 
   const sessions = createSessionStore()
   try {
-    // Namespaced by agent name so the same --session id reused across two
-    // different agents doesn't read/write the same underlying log.
+    // SessionStore itself is agent-agnostic — the same --session id reused
+    // across two different agents would otherwise read and write the same
+    // underlying log (see adapters/http.ts's identical fix). Namespacing
+    // by agent name here is what actually keeps them isolated.
     const text = await sessions.withSession(`${agent}:${sessionId}`, async (history) => {
       const result = await runAgent(entry.config, entry.createModelCall(), message, history, {
-        onEvent: (event, detail) => console.error(`[${event}]`, detail),
+        channel: 'cli',
+        onEvent: json
+          ? printJsonEvent
+          : (event) => {
+              const { type, ...detail } = event
+              console.error(`[${type}]`, detail)
+            },
       })
+      // Same synthetic 'done' event adapters/http.ts's streaming route
+      // sends once a turn is over — covers a genuine finish and both
+      // synthetic stopReasons alike, so a --json consumer always sees
+      // exactly one terminal event regardless of how the turn actually
+      // ended.
+      if (json) printJsonEvent({ type: 'done', text: result.text, ...(result.stopReason ? { stopReason: result.stopReason } : {}) })
       return { newMessages: result.newMessages, result: result.text }
     })
-    console.log(text)
+    if (!json) console.log(text)
+  } catch (err) {
+    // Mirrors adapters/http.ts's own in-band 'error' SSE event — in
+    // --json mode the turn may already have written partial output to
+    // stdout, so the failure needs to land there too, not just as an
+    // uncaught rejection's stack trace on stderr.
+    if (json) {
+      printJsonEvent({ type: 'error', error: err instanceof Error ? err.message : String(err) })
+      process.exitCode = 1
+      return
+    }
+    throw err
   } finally {
     await sessions.close()
   }