create-loopengine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evan Yan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+export interface ScaffoldOptions {
+    name: string;
+    /** Defaults to `./<name>`. */
+    destinationDir?: string;
+    templateDir?: string;
+}
+export declare function scaffold(options: ScaffoldOptions): string;
+export declare function main(argv?: string[]): void;

package/dist/cli.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { cpSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// Template ships in `template/` next to `dist/`, not inside it — it's a
+// real, buildable project (its own package.json/tsconfig), not TypeScript
+// source belonging to this CLI.
+const DEFAULT_TEMPLATE_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'template');
+export function scaffold(options) {
+    const { name } = options;
+    const templateDir = options.templateDir ?? DEFAULT_TEMPLATE_DIR;
+    const destination = options.destinationDir ?? name;
+    if (existsSync(destination)) {
+        throw new Error(`${destination} already exists — remove it or choose a different name.`);
+    }
+    mkdirSync(destination, { recursive: true });
+    cpSync(templateDir, destination, { recursive: true });
+    const pkgPath = join(destination, 'package.json');
+    const pkg = readFileSync(pkgPath, 'utf8').replace('__PROJECT_NAME__', name);
+    writeFileSync(pkgPath, pkg);
+    const readmePath = join(destination, 'README.md');
+    const readme = readFileSync(readmePath, 'utf8').replace('__PROJECT_NAME__', name);
+    writeFileSync(readmePath, readme);
+    return destination;
+}
+function parseArgs(argv) {
+    return { name: argv[0] ?? 'my-agents' };
+}
+export function main(argv = process.argv.slice(2)) {
+    try {
+        const { name } = parseArgs(argv);
+        const destination = scaffold({ name });
+        console.log(`Created ${destination}/`);
+        console.log();
+        console.log(`  cd ${destination}`);
+        console.log('  npm install');
+        console.log('  cp .env.example .env   # fill in ANTHROPIC_API_KEY');
+        console.log('  npm run dev');
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+    }
+}
+// A package-manager shim (npx, node_modules/.bin) invokes this file through
+// a symlink, not its real path — process.argv[1] is the symlink's path,
+// while Node resolves import.meta.url to the real path when loading an ES
+// module. Comparing the raw argv[1] against the resolved module URL fails
+// in exactly that case and main() silently never runs — realpath argv[1]
+// first so both sides are resolved. (Same bug, same fix, as skillgarden's
+// CLI — see its git history for the live symlink repro.)
+function isMain() {
+    if (!process.argv[1])
+        return false;
+    try {
+        return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+}
+if (isMain())
+    main();

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "create-loopengine",
+  "version": "0.1.0",
+  "description": "Scaffold a new loopengine agent project — a runnable HTTP server with one example agent, in your own repo.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/evanyan22/create-loopengine.git"
+  },
+  "bin": {
+    "create-loopengine": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "template",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x dist/cli.js",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  }
+}

package/template/.env.example

@@ -0,0 +1,10 @@
+ANTHROPIC_API_KEY=
+# Using OpenAI instead? Swap agents/example-agent.ts's createModelCall for
+# createOpenAIModelCall({ model: '...' }) and set this instead:
+# OPENAI_API_KEY=
+
+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

package/template/README.md

@@ -0,0 +1,49 @@
+# __PROJECT_NAME__
+
+An agent server built with [loopengine](https://www.npmjs.com/package/loopengine).
+
+## Setup
+
+```bash
+npm install
+cp .env.example .env   # fill in ANTHROPIC_API_KEY
+```
+
+## Run
+
+```bash
+npm run dev             # HTTP server on :8787
+```
+
+```bash
+curl -X POST localhost:8787/agents/example-agent/messages \
+  -H 'content-type: application/json' \
+  -d '{"sessionId":"s1","message":"what is the weather in Boston?"}'
+```
+
+Or from the command line directly, no server needed:
+
+```bash
+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
+   `systemPrompt`, `tools`, and `rules`.
+2. Register it in `agent-registry.ts` — one line, same shape as
+   `example-agent`.
+3. Call it at `/agents/your-agent/messages`.
+
+## Project layout
+
+```
+agent-registry.ts       Maps agent name -> {config, createModelCall}
+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
+```
+
+See [loopengine's own README](https://github.com/evanyan22/loopengine) for
+the full `AgentConfig` surface, permission rules, skills, and how to wire a
+real model.

package/template/adapters/cli.ts

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// Channel adapter #1: command line.
+//
+//   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,
+// isolated session (a random id, printed to stderr so it can be reused
+// with --session <id> later to continue that conversation).
+import { randomUUID } from 'node:crypto'
+import { createSessionStore, runAgent } from 'loopengine'
+import { getEntry, listAgents } from '../agent-registry.js'
+
+function parseArgs(argv: string[]) {
+  let agent = ''
+  let session: string | undefined
+  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 rest.push(argv[i])
+  }
+  return { agent, session, message: rest.join(' ') }
+}
+
+async function main() {
+  const { agent, session, 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>"')
+    process.exit(1)
+  }
+
+  const sessionId = session ?? randomUUID()
+  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.
+    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),
+      })
+      return { newMessages: result.newMessages, result: result.text }
+    })
+    console.log(text)
+  } finally {
+    await sessions.close()
+  }
+}
+
+main()

package/template/adapters/http.ts

@@ -0,0 +1,161 @@
+// Channel adapter #2: HTTP API.
+//
+//   npm run dev
+//
+//   curl -X POST localhost:8787/agents/example-agent/messages \
+//     -H 'content-type: application/json' \
+//     -d '{"sessionId":"s1","message":"what is the weather in Boston?"}'
+//
+//   # same request, but as it happens: one SSE event per loop step
+//   curl -N -X POST localhost:8787/agents/example-agent/messages/stream \
+//     -H 'content-type: application/json' \
+//     -d '{"sessionId":"s1","message":"what is the weather in Boston?"}'
+//
+// Owns: routing by agent name, request/response shape, and (via
+// SessionStore.withSession) making sure two concurrent requests for the
+// same session don't race on read-modify-write of that session's history.
+import { randomUUID } from 'node:crypto'
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http'
+import { createSessionStore, runAgent, type AgentConfig } from 'loopengine'
+import { getEntry, type RegistryEntry } from '../agent-registry.js'
+
+const sessions = createSessionStore()
+
+// Deriving a session key from something richer than a plain client-supplied
+// id (a customer's email, a Slack channel, ...) is business logic specific
+// to what an agent is for — see AgentConfig.sessionIdFor. This is only the
+// agent-agnostic fallback: a missing sessionId just means "no ongoing
+// conversation to resume," so one is generated rather than treated as an error.
+function defaultSessionIdFor(body: Record<string, unknown>): string | undefined {
+  const sessionId = body.sessionId
+  return typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : undefined
+}
+
+function sessionIdFor(config: AgentConfig, body: Record<string, unknown>): string | undefined {
+  if (config.sessionIdFor) return config.sessionIdFor(body)
+  return defaultSessionIdFor(body) ?? randomUUID()
+}
+
+function readJsonBody(req: IncomingMessage): Promise<Record<string, unknown>> {
+  return new Promise((resolve, reject) => {
+    let data = ''
+    req.on('data', (chunk) => (data += chunk))
+    req.on('end', () => {
+      try {
+        resolve(data ? JSON.parse(data) : {})
+      } catch (err) {
+        reject(err)
+      }
+    })
+    req.on('error', reject)
+  })
+}
+
+interface ParsedRequest {
+  entry: RegistryEntry
+  message: string
+  rawSessionId: string
+  storageSessionId: string
+}
+
+type ParseResult = { ok: true; value: ParsedRequest } | { ok: false; status: number; error: string }
+
+async function parseRequest(req: IncomingMessage, agentName: string): Promise<ParseResult> {
+  const entry = getEntry(agentName)
+  if (!entry) return { ok: false, status: 404, error: `unknown agent '${agentName}'` }
+
+  const body = await readJsonBody(req)
+  const message = String(body.message ?? '')
+  const rawSessionId = sessionIdFor(entry.config, body)
+  if (!message) return { ok: false, status: 400, error: 'message is required' }
+  if (!rawSessionId) return { ok: false, status: 400, error: 'could not derive a session id from the request body' }
+
+  // Namespaced by agent name so two agents given the same sessionId don't
+  // read/write the same underlying log.
+  return { ok: true, value: { entry, message, rawSessionId, storageSessionId: `${agentName}:${rawSessionId}` } }
+}
+
+function writeSseEvent(res: ServerResponse, event: string, data: unknown): void {
+  res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`)
+}
+
+async function handleMessages(req: IncomingMessage, res: ServerResponse, agentName: string): Promise<void> {
+  const parsed = await parseRequest(req, agentName)
+  if (!parsed.ok) {
+    res.writeHead(parsed.status, { 'content-type': 'application/json' }).end(JSON.stringify({ error: parsed.error }))
+    return
+  }
+  const { entry, message, rawSessionId, storageSessionId } = parsed.value
+
+  const text = await sessions.withSession(storageSessionId, async (history) => {
+    const result = await runAgent(entry.config, entry.createModelCall(), message, history)
+    return { newMessages: result.newMessages, result: result.text }
+  })
+
+  res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ text, sessionId: rawSessionId }))
+}
+
+async function handleMessagesStream(req: IncomingMessage, res: ServerResponse, agentName: string): Promise<void> {
+  const parsed = await parseRequest(req, agentName)
+  if (!parsed.ok) {
+    res.writeHead(parsed.status, { 'content-type': 'application/json' }).end(JSON.stringify({ error: parsed.error }))
+    return
+  }
+  const { entry, message, rawSessionId, storageSessionId } = parsed.value
+
+  res.writeHead(200, {
+    'content-type': 'text/event-stream',
+    'cache-control': 'no-cache',
+    connection: 'keep-alive',
+  })
+  writeSseEvent(res, 'session', { sessionId: rawSessionId })
+
+  try {
+    await sessions.withSession(storageSessionId, async (history) => {
+      const result = await runAgent(entry.config, entry.createModelCall(), message, history, {
+        onEvent: (event, detail) => writeSseEvent(res, event, detail),
+      })
+      writeSseEvent(res, 'done', { text: result.text })
+      return { newMessages: result.newMessages, result: result.text }
+    })
+  } catch (err) {
+    writeSseEvent(res, 'error', { error: String(err) })
+  } finally {
+    res.end()
+  }
+}
+
+const server = createServer(async (req, res) => {
+  try {
+    const streamMatch = req.method === 'POST' && req.url?.match(/^\/agents\/([^/]+)\/messages\/stream$/)
+    if (streamMatch) {
+      await handleMessagesStream(req, res, decodeURIComponent(streamMatch[1]))
+      return
+    }
+
+    const match = req.method === 'POST' && req.url?.match(/^\/agents\/([^/]+)\/messages$/)
+    if (!match) {
+      res.writeHead(404, { 'content-type': 'application/json' }).end(JSON.stringify({ error: 'not found' }))
+      return
+    }
+
+    await handleMessages(req, res, decodeURIComponent(match[1]))
+  } catch (err) {
+    if (res.headersSent) {
+      res.end()
+    } else {
+      res.writeHead(500, { 'content-type': 'application/json' }).end(JSON.stringify({ error: String(err) }))
+    }
+  }
+})
+
+const port = Number(process.env.PORT ?? 8787)
+server.listen(port, () => console.log(`agent API listening on :${port}`))
+
+async function shutdown() {
+  server.close()
+  await sessions.close()
+  process.exit(0)
+}
+process.on('SIGTERM', shutdown)
+process.on('SIGINT', shutdown)

package/template/agent-registry.ts

@@ -0,0 +1,24 @@
+// Every adapter resolves "which agent" through this — the thing that
+// makes agents pluggable. Defining a new agent means adding one line here;
+// no adapter changes needed.
+import type { AgentConfig, ModelCall } from 'loopengine'
+import { config as exampleAgentConfig, createModelCall as createExampleAgentModelCall } from './agents/example-agent.js'
+
+export interface RegistryEntry {
+  config: AgentConfig
+  /** Factory, not a shared instance — a fresh ModelCall per request/session. */
+  createModelCall: () => ModelCall
+}
+
+const entries: Record<string, RegistryEntry> = {
+  'example-agent': { config: exampleAgentConfig, createModelCall: createExampleAgentModelCall },
+}
+
+export function listAgents(): string[] {
+  return Object.keys(entries)
+}
+
+/** undefined for an unknown agent name. */
+export function getEntry(name: string): RegistryEntry | undefined {
+  return entries[name]
+}

package/template/agents/example-agent.ts

@@ -0,0 +1,26 @@
+// A starting point, not a template to copy verbatim: real persona, real
+// tool, real permission rule. Add more agents by copying this file and
+// registering the new one in agent-registry.ts.
+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' })
+}

package/template/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx adapters/http.ts",
+    "cli": "tsx adapters/cli.ts"
+  },
+  "dependencies": {
+    "loopengine": "^0.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}

package/template/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist"
+  },
+  "include": ["*.ts", "adapters/*.ts", "agents/*.ts"]
+}