create-loopengine 0.1.12 → 0.1.14

package/README.md

@@ -51,6 +51,7 @@ agents/example-agent.ts   Starter agent: persona, one tool, one permission rule
 adapters/http.ts          HTTP API (streaming + non-streaming), routes by agent name
 adapters/cli.ts           Command-line adapter
 .env.example              ANTHROPIC_API_KEY / OPENAI_API_KEY / REDIS_URL
+.create-loopengine.json   Which version this project was scaffolded from — see "Upgrading" below
 ```
 
 The registry is multi-agent-capable from the start — seeded with one
@@ -84,6 +85,41 @@ working example. Not wired in here by default: it needs the `composio` CLI
 installed and an authenticated account (`composio link <toolkit>`) first,
 so it's a deliberate next step, not part of this starter agent.
 
+## Upgrading
+
+`npm install loopengine@latest` alone only picks up library-side changes
+— `adapters/http.ts`, `adapters/cli.ts`, and `agent-registry.ts` are
+copied into your project once at scaffold time and never touched by npm
+again, so template improvements (new routes, bug fixes) don't reach an
+existing project on their own. `upgrade` closes that gap with a real
+three-way merge — the same technique `git merge` uses — so your own
+edits to those files survive:
+
+```bash
+npx create-loopengine@latest upgrade
+```
+
+Run from inside your project. It merges the current template against
+whichever `create-loopengine` version your project was originally
+scaffolded from (recorded in `.create-loopengine.json`, written
+automatically at scaffold time — pass `--from <version>` if that file is
+missing, e.g. for a project scaffolded before this command existed).
+Each of the five template-owned files gets one of:
+
+- **unchanged** — the template never touched this file between your
+  version and the latest; nothing to merge, nothing overwritten.
+- **updated** — merged cleanly; your own edits and the template's own
+  changes didn't overlap.
+- **conflict** — you edited the same lines the template changed. The
+  file is written with real `<<<<<<<`/`=======`/`>>>>>>>` markers, same
+  as any git merge conflict — resolve them by hand, then `npx tsc
+  --noEmit` to confirm it builds.
+
+`upgrade` never touches `agents/`, `README.md`, `.env.example`, or
+`package.json`'s own dependency versions — run `npm install
+loopengine@latest` (and `actauth`/`skillgarden` if you use them directly)
+separately to pick those up.
+
 ## Status
 
 Verified end to end against the real published packages: `npm create

package/dist/cli.d.ts

@@ -6,4 +6,31 @@ export interface ScaffoldOptions {
     templateDir?: string;
 }
 export declare function scaffold(options: ScaffoldOptions): string;
+export type UpgradeFileStatus = 'updated' | 'unchanged' | 'conflict' | 'skipped';
+export interface UpgradeFileResult {
+    file: string;
+    status: UpgradeFileStatus;
+}
+export interface UpgradeResult {
+    fromVersion: string;
+    toVersion: string;
+    files: UpgradeFileResult[];
+}
+export interface UpgradeOptions {
+    /** Defaults to process.cwd(). */
+    projectDir?: string;
+    /** Overrides the version recorded in .create-loopengine.json — required
+     * if that file is missing (a project scaffolded before this command
+     * existed) or was removed. */
+    from?: string;
+    /** Test-only override for the "current" template — defaults to this
+     * CLI's own bundled template/, same as ScaffoldOptions.templateDir. */
+    currentTemplateDir?: string;
+    /** Resolves the historical template directory for a given
+     * create-loopengine version — defaults to fetchPublishedTemplateDir
+     * (a real `npm pack`). Test-only seam to avoid hitting the real
+     * registry for a fixture "old" template. */
+    resolveBaseTemplateDir?: (version: string) => string;
+}
+export declare function upgradeProject(options?: UpgradeOptions): UpgradeResult;
 export declare function main(argv?: string[]): void;

package/dist/cli.js

@@ -1,11 +1,23 @@
 #!/usr/bin/env node
-import { cpSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
 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');
+// This CLI's own version — embedded in a scaffolded project's own
+// .create-loopengine.json (see scaffold() below) as the future upgrade
+// command's merge base, and used again here as the "to" version once
+// upgradeProject() actually runs. Read at runtime rather than baked in
+// at build time so a locally-linked/packed build always reports its own
+// real package.json, not a stale constant.
+function ownVersion() {
+    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+    return JSON.parse(readFileSync(pkgPath, 'utf8')).version;
+}
 export function scaffold(options) {
     const { name } = options;
     const templateDir = options.templateDir ?? DEFAULT_TEMPLATE_DIR;
@@ -25,13 +37,169 @@ export function scaffold(options) {
     const readmePath = join(destination, 'README.md');
     const readme = readFileSync(readmePath, 'utf8').replace('__PROJECT_NAME__', name);
     writeFileSync(readmePath, readme);
+    // Records which create-loopengine version this project's copied,
+    // hand-editable files (adapters/http.ts, agent-registry.ts, ...) last
+    // matched — the merge base `upgrade` needs to pull in template changes
+    // later without clobbering whatever's been hand-edited since. Tracked
+    // like package.json/lockfiles (committed, not gitignored): it's project
+    // metadata, not a build artifact.
+    writeFileSync(join(destination, '.create-loopengine.json'), JSON.stringify({ version: ownVersion() }, null, 2) + '\n');
     return destination;
 }
+// ---- upgrade: pulls template improvements into an already-scaffolded
+// project's own copied files (adapters/http.ts, adapters/cli.ts,
+// agent-registry.ts, tsconfig.json, .gitignore) via a real three-way
+// merge — the same technique `git merge`/`rebase` use, applied here
+// because those files are meant to be hand-edited after scaffolding, not
+// re-imported from a package the way core library code is. See
+// scaffold()'s own .create-loopengine.json write above for the "base"
+// version this merge starts from. ----
+// templatePath is where the file lives inside a template/ directory
+// (base or current); projectPath is where the *scaffolded* copy lives —
+// only differs for _gitignore, which scaffold() renames to .gitignore
+// (see its own comment for why the template can't ship it under that
+// name directly). Deliberately narrow: agents/example-agent/** stops
+// being "template" the instant someone builds a real agent on top of it,
+// and package.json's own dependency versions are a separate, simpler
+// `npm install loopengine@latest` left to the operator rather than
+// merged here.
+const UPGRADE_CANDIDATE_FILES = [
+    { templatePath: 'adapters/http.ts', projectPath: 'adapters/http.ts' },
+    { templatePath: 'adapters/cli.ts', projectPath: 'adapters/cli.ts' },
+    { templatePath: 'agent-registry.ts', projectPath: 'agent-registry.ts' },
+    { templatePath: 'tsconfig.json', projectPath: 'tsconfig.json' },
+    { templatePath: '_gitignore', projectPath: '.gitignore' },
+];
+// npm keeps every published tarball forever, so the historical template
+// for *any* previously-released version is always fetchable this way —
+// no separate snapshot storage, no git-tag dependency. `npm pack`
+// extracts to a `package/` directory inside whatever `--pack-destination`
+// it's given, same as every other real-package verification already done
+// this way elsewhere in this project's own test suite.
+function fetchPublishedTemplateDir(version) {
+    const workDir = mkdtempSync(join(tmpdir(), 'create-loopengine-upgrade-base-'));
+    execFileSync('npm', ['pack', `create-loopengine@${version}`, '--pack-destination', workDir], { stdio: 'pipe' });
+    const tarball = readdirSync(workDir).find((f) => f.endsWith('.tgz'));
+    if (!tarball) {
+        throw new Error(`Could not fetch create-loopengine@${version} from npm — check the version exists and you have network access.`);
+    }
+    // Absolute path, not the bare filename readdirSync returns — tar
+    // resolves a relative first argument against the calling process's own
+    // cwd (wherever `create-loopengine upgrade` was actually run from), not
+    // workDir, even with -C set (-C only affects where extraction lands).
+    // Confirmed live: this failed with a wrong-directory ENOENT.
+    execFileSync('tar', ['-xzf', join(workDir, tarball), '-C', workDir], { stdio: 'pipe' });
+    return join(workDir, 'package', 'template');
+}
+// git merge-file's own exit code *is* its conflict count (0 = clean),
+// not a pass/fail signal — execFileSync throws on any non-zero exit, so
+// a real conflict has to be told apart from git genuinely failing to
+// run (not installed, path error: no `status`, an `ENOENT`-shaped error
+// instead) by checking for a numeric `status` on the caught error.
+// Operates on `minePath` in place (git merge-file's own contract) — always
+// called with a disposable temp copy, never the real project file
+// directly, so the caller decides whether/how to apply the result.
+function threeWayMerge(minePath, basePath, theirsPath) {
+    let conflicted = false;
+    try {
+        execFileSync('git', ['merge-file', '--diff3', '-L', 'mine', '-L', 'base', '-L', 'latest', minePath, basePath, theirsPath], {
+            stdio: 'pipe',
+        });
+    }
+    catch (err) {
+        if (err && typeof err === 'object' && 'status' in err && typeof err.status === 'number') {
+            conflicted = true;
+        }
+        else {
+            throw new Error(`git merge-file failed — is git installed and on PATH? (${err instanceof Error ? err.message : String(err)})`);
+        }
+    }
+    return { merged: readFileSync(minePath, 'utf8'), conflicted };
+}
+function upgradeFile(candidate, baseTemplateDir, currentTemplateDir, projectDir) {
+    const projectFilePath = join(projectDir, candidate.projectPath);
+    const baseFilePath = join(baseTemplateDir, candidate.templatePath);
+    const theirsFilePath = join(currentTemplateDir, candidate.templatePath);
+    if (!existsSync(projectFilePath) || !existsSync(baseFilePath) || !existsSync(theirsFilePath)) {
+        return { file: candidate.projectPath, status: 'skipped' };
+    }
+    const base = readFileSync(baseFilePath, 'utf8');
+    const theirs = readFileSync(theirsFilePath, 'utf8');
+    if (base === theirs) {
+        // The template never touched this file between the recorded version
+        // and now — nothing to merge, and importantly nothing to overwrite,
+        // so a hand-edit here is never even diffed against, let alone at risk.
+        return { file: candidate.projectPath, status: 'unchanged' };
+    }
+    const mine = readFileSync(projectFilePath, 'utf8');
+    const scratchDir = mkdtempSync(join(tmpdir(), 'create-loopengine-merge-'));
+    const mineTmp = join(scratchDir, 'mine');
+    const baseTmp = join(scratchDir, 'base');
+    const theirsTmp = join(scratchDir, 'theirs');
+    writeFileSync(mineTmp, mine);
+    writeFileSync(baseTmp, base);
+    writeFileSync(theirsTmp, theirs);
+    const { merged, conflicted } = threeWayMerge(mineTmp, baseTmp, theirsTmp);
+    rmSync(scratchDir, { recursive: true, force: true });
+    writeFileSync(projectFilePath, merged);
+    return { file: candidate.projectPath, status: conflicted ? 'conflict' : 'updated' };
+}
+export function upgradeProject(options = {}) {
+    const projectDir = options.projectDir ?? process.cwd();
+    const currentTemplateDir = options.currentTemplateDir ?? DEFAULT_TEMPLATE_DIR;
+    const toVersion = ownVersion();
+    const provenancePath = join(projectDir, '.create-loopengine.json');
+    let fromVersion = options.from;
+    if (!fromVersion) {
+        if (!existsSync(provenancePath)) {
+            throw new Error(`No .create-loopengine.json in ${projectDir} — this project was scaffolded before \`upgrade\` existed, or the file was removed. Pass --from <version> to specify which create-loopengine version it was originally scaffolded from.`);
+        }
+        const provenance = JSON.parse(readFileSync(provenancePath, 'utf8'));
+        if (!provenance.version) {
+            throw new Error(`${provenancePath} is missing its "version" field — pass --from <version> instead.`);
+        }
+        fromVersion = provenance.version;
+    }
+    const resolveBase = options.resolveBaseTemplateDir ?? fetchPublishedTemplateDir;
+    const baseTemplateDir = resolveBase(fromVersion);
+    const files = UPGRADE_CANDIDATE_FILES.map((candidate) => upgradeFile(candidate, baseTemplateDir, currentTemplateDir, projectDir));
+    writeFileSync(provenancePath, JSON.stringify({ version: toVersion }, null, 2) + '\n');
+    return { fromVersion, toVersion, files };
+}
+function parseUpgradeArgs(argv) {
+    let from;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--from')
+            from = argv[++i];
+    }
+    return { from };
+}
+function printUpgradeSummary(result) {
+    console.log(`Upgrading create-loopengine@${result.fromVersion} -> @${result.toVersion}`);
+    console.log();
+    for (const f of result.files) {
+        const label = f.status === 'updated' ? 'updated  ' : f.status === 'conflict' ? 'conflict ' : f.status === 'unchanged' ? 'unchanged' : 'skipped  ';
+        console.log(`  ${label}  ${f.file}`);
+    }
+    console.log();
+    const conflicted = result.files.filter((f) => f.status === 'conflict');
+    if (conflicted.length > 0) {
+        console.log(`${conflicted.length} file(s) have <<<<<<< conflict markers to resolve by hand before this will build.`);
+    }
+    else {
+        console.log('No conflicts. Run `npm install loopengine@latest` to pick up any library-side changes too.');
+    }
+}
 function parseArgs(argv) {
     return { name: argv[0] ?? 'my-agents' };
 }
 export function main(argv = process.argv.slice(2)) {
     try {
+        if (argv[0] === 'upgrade') {
+            const { from } = parseUpgradeArgs(argv.slice(1));
+            printUpgradeSummary(upgradeProject({ from }));
+            return;
+        }
         const { name } = parseArgs(argv);
         const destination = scaffold({ name });
         console.log(`Created ${destination}/`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-loopengine",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "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/adapters/http.ts

@@ -43,6 +43,7 @@ import {
   AgentEditNotSupportedError,
   AgentFileNotFoundError,
   type AgentEditResult,
+  type AgentEditableFields,
   createSessionStore,
   createCheckpointStore,
   type TurnCheckpoint,
@@ -79,6 +80,10 @@ import {
   deleteSkill,
   SkillInvalidIdError,
   SkillNotFoundError,
+  listSkillgardenCatalog,
+  readSkillgardenCatalogEntry,
+  addSkillgardenSkillToAgent,
+  SkillgardenUnavailableError,
   readActauthConfig,
   addActauthRule,
   updateActauthRule,
@@ -314,9 +319,14 @@ async function describeAgent(entry: RegistryEntry): Promise<Record<string, unkno
   // configured for *this* agent, so the config page's own Skills tab
   // deliberately doesn't mix it into skills/skillsDirs below.
   const skillsDirs = config.skillsDirs ?? [`agents/${config.name}/skills`]
-  const skillGarden = new SkillGarden({ dirs: skillsDirs, indexBudgetTokens: config.skillIndexBudgetTokens ?? 200 })
+  // Same defaults, same reasoning, as loopengine's own run-agent.ts
+  // SkillGarden/BudgetTracker construction — kept in sync there and here
+  // since this is what a "Skills"/"Limits & budgets" tab shows an
+  // operator, and it has to describe what runAgent() would actually
+  // resolve, not a second guess (see this function's own header comment).
+  const skillGarden = new SkillGarden({ dirs: skillsDirs, indexBudgetTokens: config.skillIndexBudgetTokens ?? 2000 })
   const skillIndex = skillGarden.buildIndex().included
-  const systemSkillGarden = new SkillGarden({ dirs: [systemSkillsDir], indexBudgetTokens: config.skillIndexBudgetTokens ?? 200 })
+  const systemSkillGarden = new SkillGarden({ dirs: [systemSkillsDir], indexBudgetTokens: config.skillIndexBudgetTokens ?? 2000 })
   const systemSkillIndex = systemSkillGarden.buildIndex().included
 
   return {
@@ -326,8 +336,8 @@ async function describeAgent(entry: RegistryEntry): Promise<Record<string, unkno
       ? { provider: config.model.provider, model: config.model.model, maxTokens: config.model.maxTokens }
       : 'custom (module exports its own createModelCall)',
     maxTurns: config.maxTurns ?? 25,
-    contextBudgetTokens: config.contextBudgetTokens ?? 8000,
-    skillIndexBudgetTokens: config.skillIndexBudgetTokens ?? 200,
+    contextBudgetTokens: config.contextBudgetTokens ?? 100000,
+    skillIndexBudgetTokens: config.skillIndexBudgetTokens ?? 2000,
     skillsDirs: skillsDirs,
     skills: skillIndex.map((s) => ({ name: s.name, description: s.description })),
     systemSkills: systemSkillIndex.map((s) => ({ name: s.name, description: s.description })),
@@ -644,6 +654,33 @@ function parseAgentTemplateOptions(body: Record<string, unknown>): { ok: true; v
   return { ok: true, value: options }
 }
 
+// The Overview tab's "Limits & budgets" edit form — kept separate from
+// parseAgentTemplateOptions since that one's shape (AgentTemplateOptions)
+// is shared with handleCreateAgent/scaffoldAgent, which has no notion of
+// these three at all (a freshly scaffolded agent always starts on
+// loopengine's own defaults — see AgentConfig's own doc comments). Each
+// of the three is optional and independent, same as systemPrompt/model
+// above.
+function parsePositiveInt(value: unknown, field: string): { ok: true; value: number | undefined } | { ok: false; error: string } {
+  if (value === undefined || value === null) return { ok: true, value: undefined }
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
+    return { ok: false, error: `${field} must be a positive integer` }
+  }
+  return { ok: true, value }
+}
+
+function parseAgentLimitsFields(
+  body: Record<string, unknown>,
+): { ok: true; value: Pick<AgentEditableFields, 'maxTurns' | 'contextBudgetTokens' | 'skillIndexBudgetTokens'> } | { ok: false; error: string } {
+  const value: Pick<AgentEditableFields, 'maxTurns' | 'contextBudgetTokens' | 'skillIndexBudgetTokens'> = {}
+  for (const field of ['maxTurns', 'contextBudgetTokens', 'skillIndexBudgetTokens'] as const) {
+    const parsed = parsePositiveInt(body[field], field)
+    if (!parsed.ok) return parsed
+    if (parsed.value !== undefined) value[field] = parsed.value
+  }
+  return { ok: true, value }
+}
+
 async function handleCreateAgent(req: IncomingMessage, res: ServerResponse): Promise<void> {
   const body = await readJsonBody(req)
   if (typeof body.name !== 'string' || !body.name) {
@@ -677,9 +714,11 @@ async function handleCreateAgent(req: IncomingMessage, res: ServerResponse): Pro
   res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ path: indexPath, registered: true }))
 }
 
-// Backs the Overview tab's System prompt / Model edit forms — either
-// field can be sent independently (see parseAgentTemplateOptions), the
-// other stays untouched both on disk and live. Persists via
+// Backs the Overview tab's System prompt / Model / Limits & budgets edit
+// forms — any subset of systemPrompt, model, maxTurns, contextBudgetTokens,
+// skillIndexBudgetTokens can be sent independently (see
+// parseAgentTemplateOptions/parseAgentLimitsFields), every other field
+// stays untouched both on disk and live. Persists via
 // agent-file-admin.ts's editAgentFile (see its own doc comment for why
 // this is a surgical AST edit, not a full file regeneration), then
 // applies the exact same resolved values to *this* running process via
@@ -699,14 +738,22 @@ async function handleEditAgent(req: IncomingMessage, res: ServerResponse, agentN
     res.writeHead(400, { 'content-type': 'application/json' }).end(JSON.stringify({ error: parsedOptions.error }))
     return
   }
-  if (parsedOptions.value.systemPrompt === undefined && parsedOptions.value.model === undefined) {
-    res.writeHead(400, { 'content-type': 'application/json' }).end(JSON.stringify({ error: 'systemPrompt or model is required' }))
+  const parsedLimits = parseAgentLimitsFields(body)
+  if (!parsedLimits.ok) {
+    res.writeHead(400, { 'content-type': 'application/json' }).end(JSON.stringify({ error: parsedLimits.error }))
+    return
+  }
+  const editFields: AgentEditableFields = { ...parsedOptions.value, ...parsedLimits.value }
+  if (Object.keys(editFields).length === 0) {
+    res
+      .writeHead(400, { 'content-type': 'application/json' })
+      .end(JSON.stringify({ error: 'systemPrompt, model, maxTurns, contextBudgetTokens, or skillIndexBudgetTokens is required' }))
     return
   }
 
   let result: AgentEditResult
   try {
-    result = editAgentFile(agentName, parsedOptions.value)
+    result = editAgentFile(agentName, editFields)
   } catch (err) {
     const status =
       err instanceof AgentEditNotSupportedError || err instanceof AgentModelError ? 400 : err instanceof AgentFileNotFoundError ? 404 : 500
@@ -716,6 +763,9 @@ async function handleEditAgent(req: IncomingMessage, res: ServerResponse, agentN
 
   const configPatch: Partial<AgentConfig> = {}
   if (result.systemPrompt !== undefined) configPatch.systemPrompt = result.systemPrompt
+  if (result.maxTurns !== undefined) configPatch.maxTurns = result.maxTurns
+  if (result.contextBudgetTokens !== undefined) configPatch.contextBudgetTokens = result.contextBudgetTokens
+  if (result.skillIndexBudgetTokens !== undefined) configPatch.skillIndexBudgetTokens = result.skillIndexBudgetTokens
   let createModelCall: RegistryEntry['createModelCall'] | undefined
   if (result.model) {
     configPatch.model = result.model
@@ -782,6 +832,69 @@ function handleSkillDelete(res: ServerResponse, agentName: string, skillId: stri
   res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ ok: true }))
 }
 
+// Backs the Skills tab's "Browse skillgarden catalog" section — a
+// read-only, agent-independent list of everything skillgarden ships in
+// its own bundled registry (see loopengine's own web/skillgarden-admin.ts).
+// Not wrapped in a per-agent :name segment since the catalog itself
+// isn't scoped to any one agent; only the POST below (actually
+// installing an entry) is.
+function handleSkillgardenCatalogGet(res: ServerResponse): void {
+  try {
+    // Computed before writeHead, not inlined into .end()'s own argument —
+    // res.writeHead(200, ...) commits the status line the instant it's
+    // called, so a throw evaluated *after* it (as it would be if it were
+    // inlined as .end()'s argument) leaves headers already sent as 200
+    // with no body, and the catch block's own writeHead(status, ...)
+    // then fails outright (ERR_HTTP_HEADERS_SENT) instead of ever
+    // reaching the client.
+    const catalog = listSkillgardenCatalog()
+    res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify(catalog))
+  } catch (err) {
+    const status = err instanceof SkillgardenUnavailableError ? 503 : 500
+    res.writeHead(status, { 'content-type': 'application/json' }).end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }))
+  }
+}
+
+// Full SKILL.md body for the catalog's own "View" toggle — kept as a
+// separate route from the list above (rather than inlining every body
+// into it) for the same reason the Skills tab's own edit form fetches a
+// skill's body lazily instead of shipping it in the initial list.
+function handleSkillgardenCatalogEntryGet(res: ServerResponse, category: string, id: string): void {
+  try {
+    // See handleSkillgardenCatalogGet's own comment for why this is
+    // computed before writeHead rather than inlined into .end()'s
+    // argument.
+    const entry = readSkillgardenCatalogEntry(category, id)
+    res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify(entry))
+  } catch (err) {
+    const status = err instanceof SkillgardenUnavailableError ? 503 : 404
+    res.writeHead(status, { 'content-type': 'application/json' }).end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }))
+  }
+}
+
+// Installs a catalog entry into agents/:name/skills/ — delegates to
+// skillgarden's own addSkill (see skillgarden-admin.ts), which throws
+// plain Errors (no typed classes) for "unknown skill"/"already exists",
+// so those two are told apart by message shape rather than instanceof,
+// same as any other dependency that doesn't export typed errors for its
+// own failure modes.
+async function handleSkillgardenCatalogAdd(req: IncomingMessage, res: ServerResponse, agentName: string, category: string, id: string): Promise<void> {
+  if (!getEntry(agentName)) {
+    res.writeHead(404, { 'content-type': 'application/json' }).end(JSON.stringify({ error: `unknown agent '${agentName}'` }))
+    return
+  }
+  const body = await readJsonBody(req)
+  const force = body.force === true
+  try {
+    const result = addSkillgardenSkillToAgent(agentName, category, id, force)
+    res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ ok: true, id: result.id }))
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    const status = err instanceof SkillgardenUnavailableError ? 503 : /already exists/.test(message) ? 409 : /^Unknown skill/.test(message) ? 404 : 500
+    res.writeHead(status, { 'content-type': 'application/json' }).end(JSON.stringify({ error: message }))
+  }
+}
+
 // Backs the Actauth tab's rule editor — parses a rule body shared by both
 // the add (POST) and update (PUT, minus `name`) routes below.
 function parseActauthRuleBody(body: Record<string, unknown>, requireName: boolean): { ok: true; value: { name: string; scope: string; tool: string; decision: Decision } } | { ok: false; error: string } {
@@ -1906,6 +2019,23 @@ const server = createServer(async (req, res) => {
       return
     }
 
+    // Backs the Skills tab's "Browse skillgarden catalog" section — see
+    // the three handlers above it.
+    if (req.method === 'GET' && pathname === '/skillgarden-catalog') {
+      handleSkillgardenCatalogGet(res)
+      return
+    }
+    const skillgardenEntryMatch = req.method === 'GET' && pathname.match(/^\/skillgarden-catalog\/([^/]+)\/([^/]+)$/)
+    if (skillgardenEntryMatch) {
+      handleSkillgardenCatalogEntryGet(res, decodeURIComponent(skillgardenEntryMatch[1]), decodeURIComponent(skillgardenEntryMatch[2]))
+      return
+    }
+    const skillgardenAddMatch = req.method === 'POST' && pathname.match(/^\/agents\/([^/]+)\/skillgarden-catalog\/([^/]+)\/([^/]+)$/)
+    if (skillgardenAddMatch) {
+      await handleSkillgardenCatalogAdd(req, res, decodeURIComponent(skillgardenAddMatch[1]), decodeURIComponent(skillgardenAddMatch[2]), decodeURIComponent(skillgardenAddMatch[3]))
+      return
+    }
+
     // Backs the Actauth tab's rule editor and default_decision control.
     // The default-decision route is checked before the :ruleName routes
     // right below since 'default-decision' would otherwise itself match

package/template/package.json

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