create-loopengine 0.1.9 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-loopengine",
-  "version": "0.1.9",
+  "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,6 +31,23 @@ 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/` to `agents/your-agent/` — `index.ts`

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()
   }