loopengine 0.1.3 → 0.1.5

package/dist/web/skills-admin.d.ts

@@ -0,0 +1,23 @@
+export declare class SkillInvalidIdError extends Error {
+}
+export declare class SkillNotFoundError extends Error {
+}
+export interface SkillContent {
+    id: string;
+    description: string;
+    body: string;
+}
+export declare function readSkill(agentName: string, skillId: string): SkillContent;
+/** Creates the skill if `skillId` doesn't exist yet, or overwrites it in
+ * place if it does — same "this is the new content, not a diff to
+ * merge" semantics as a PUT. Frontmatter is regenerated from `skillId`
+ * (as `name`) and `description`; any *other* frontmatter keys a skill
+ * might have (e.g. `paths` — see SkillFrontmatter's own doc comment) are
+ * intentionally not preserved here, since this admin UI has no field for
+ * them. A skill that needs those is still editable by hand — this just
+ * isn't the tool for it. */
+export declare function writeSkill(agentName: string, skillId: string, content: {
+    description: string;
+    body: string;
+}): void;
+export declare function deleteSkill(agentName: string, skillId: string): void;

package/dist/web/skills-admin.js

@@ -0,0 +1,67 @@
+// Lets an operator add, edit, or remove a skill from the Skills tab in
+// /agents/config, instead of hand-writing agents/<name>/skills/<id>/
+// SKILL.md directly. Deliberately scoped to *flat* skills only — a
+// nested skill (e.g. agents/<name>/skills/deploy/web/SKILL.md, which
+// SkillGarden's own discoverSkillFiles namespaces as 'deploy:web') isn't
+// addressable through this admin surface; its id would need to carry a
+// '/' through a single URL path segment, which either means encoding
+// tricks or a second routing scheme, for a nesting feature nothing in
+// this repo's own example agents actually uses. Read-only display of a
+// nested skill (via describeAgent's own skills list) still works fine —
+// only adding/editing/removing one through this UI is out of scope.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { parseSkillFile } from 'skillgarden';
+import { agentDir } from '../core/gateway-tools.js';
+export class SkillInvalidIdError extends Error {
+}
+export class SkillNotFoundError extends Error {
+}
+// Same character set agent/subagent names are already validated against
+// elsewhere in this repo (bin/cli.ts's NAME_PATTERN) — a skill id becomes a
+// directory name on disk, so this is what keeps it from ever containing
+// '/', '..', or anything else that could resolve outside its own
+// skills/ folder.
+const SKILL_ID_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+function requireValidSkillId(skillId) {
+    if (!SKILL_ID_PATTERN.test(skillId)) {
+        throw new SkillInvalidIdError(`Invalid skill id '${skillId}' — must be lowercase, alphanumeric, hyphen-separated (e.g. "summarize-files"); nested skills aren't editable through this admin UI.`);
+    }
+}
+function skillsDir(agentName) {
+    return join(agentDir(agentName), 'skills');
+}
+function skillFilePath(agentName, skillId) {
+    requireValidSkillId(skillId);
+    return join(skillsDir(agentName), skillId, 'SKILL.md');
+}
+export function readSkill(agentName, skillId) {
+    const path = skillFilePath(agentName, skillId);
+    if (!existsSync(path)) {
+        throw new SkillNotFoundError(`No skill '${skillId}' for '${agentName}'.`);
+    }
+    const { frontmatter, body } = parseSkillFile(readFileSync(path, 'utf8'), skillId);
+    return { id: skillId, description: frontmatter.description ?? '', body };
+}
+/** Creates the skill if `skillId` doesn't exist yet, or overwrites it in
+ * place if it does — same "this is the new content, not a diff to
+ * merge" semantics as a PUT. Frontmatter is regenerated from `skillId`
+ * (as `name`) and `description`; any *other* frontmatter keys a skill
+ * might have (e.g. `paths` — see SkillFrontmatter's own doc comment) are
+ * intentionally not preserved here, since this admin UI has no field for
+ * them. A skill that needs those is still editable by hand — this just
+ * isn't the tool for it. */
+export function writeSkill(agentName, skillId, content) {
+    const path = skillFilePath(agentName, skillId);
+    const description = content.description.replace(/\n/g, ' ').trim();
+    const frontmatter = `---\nname: ${skillId}\ndescription: ${JSON.stringify(description)}\n---\n\n`;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, frontmatter + content.body.trim() + '\n');
+}
+export function deleteSkill(agentName, skillId) {
+    const path = skillFilePath(agentName, skillId);
+    if (!existsSync(path)) {
+        throw new SkillNotFoundError(`No skill '${skillId}' for '${agentName}'.`);
+    }
+    rmSync(dirname(path), { recursive: true, force: true });
+}

package/dist/web/web-approver.d.ts

@@ -0,0 +1,35 @@
+import { WebchatApprover, type PendingApproval } from 'actauth';
+/** Every WebchatApprover a request might end up using should be created
+ * through this, not `new WebchatApprover()` directly — the id it hands out
+ * on each new pending approval is otherwise unreachable from
+ * decideApproval()/listApprovals() below. Both adapters/http.ts routes
+ * call this once per turn, with that turn's own sessionId: the streaming
+ * route wires onPending to an SSE event on that exact response so the
+ * approval popup appears inline in the conversation that's actually
+ * blocked on it; the plain route wires it to resolve the early-return
+ * race handleMessages uses instead of blocking indefinitely (see its own
+ * doc comment) — same reason, no HTTP request should hang on a human
+ * with nothing telling the caller that's what's happening. */
+export declare function createTrackedApprover(sessionId: string, onPending?: (approval: PendingApproval) => void): WebchatApprover;
+/** Every currently-pending approval, from any tracked instance. Unfiltered
+ * (both omitted) returns every approval pending anywhere in this process,
+ * across every agent, tenant, and session — real uses (an operator's own
+ * admin view, say) should filter; both agent and session scoping are
+ * exact (agent from actauth's own Scope, already on every PendingApproval;
+ * session from sessionByApprover, always known — see its own doc
+ * comment). */
+export declare function listApprovals(filter?: {
+    agent?: string;
+    sessionId?: string;
+}): PendingApproval[];
+/** Routes to whichever WebchatApprover instance actually owns `id` — the
+ * caller doesn't need to know which turn/session created it. */
+export declare function decideApproval(id: string, approved: boolean): boolean;
+/** Peek at a pending approval's own entry and owning session, without
+ * deciding it — adapters/http.ts needs this *before* calling
+ * decideApproval() above, to know which turn's early-return race (see its
+ * own sessionTurns) to resume once this one's decided. */
+export declare function findApproval(id: string): {
+    approval: PendingApproval;
+    sessionId: string;
+} | undefined;

package/dist/web/web-approver.js

@@ -0,0 +1,88 @@
+// adapters/http.ts's wiring around actauth's WebchatApprover (see its own
+// approvers.ts) — one process can have several WebchatApprover instances
+// live at once (see createTrackedApprover's own doc comment for why),
+// so POST /approvals/:id/approve|deny needs to know which instance
+// actually owns a given pending id before it can call decide() on it.
+// That routing table is what this file owns; the approver class itself
+// stays in actauth, generic and framework-agnostic.
+import { WebchatApprover } from 'actauth';
+const approversById = new Map();
+// Which session each *instance* is serving — not each pending approval,
+// because a single WebchatApprover instance only ever needs to serve one
+// session's worth of calls: both adapters/http.ts routes now create a
+// fresh tracked approver per call (see createTrackedApprover's own doc
+// comment), so this is always known, not best-effort. A WeakMap, not a
+// Map, so an old instance (nothing else references it once its own
+// approvals are gone) doesn't get held alive forever just for this
+// bookkeeping.
+const sessionByApprover = new WeakMap();
+/** Every WebchatApprover a request might end up using should be created
+ * through this, not `new WebchatApprover()` directly — the id it hands out
+ * on each new pending approval is otherwise unreachable from
+ * decideApproval()/listApprovals() below. Both adapters/http.ts routes
+ * call this once per turn, with that turn's own sessionId: the streaming
+ * route wires onPending to an SSE event on that exact response so the
+ * approval popup appears inline in the conversation that's actually
+ * blocked on it; the plain route wires it to resolve the early-return
+ * race handleMessages uses instead of blocking indefinitely (see its own
+ * doc comment) — same reason, no HTTP request should hang on a human
+ * with nothing telling the caller that's what's happening. */
+export function createTrackedApprover(sessionId, onPending) {
+    let approver;
+    approver = new WebchatApprover({
+        onPending: (approval) => {
+            approversById.set(approval.id, approver);
+            onPending?.(approval);
+        },
+        onSettled: (id) => {
+            approversById.delete(id);
+        },
+    });
+    sessionByApprover.set(approver, sessionId);
+    return approver;
+}
+/** Every currently-pending approval, from any tracked instance. Unfiltered
+ * (both omitted) returns every approval pending anywhere in this process,
+ * across every agent, tenant, and session — real uses (an operator's own
+ * admin view, say) should filter; both agent and session scoping are
+ * exact (agent from actauth's own Scope, already on every PendingApproval;
+ * session from sessionByApprover, always known — see its own doc
+ * comment). */
+export function listApprovals(filter) {
+    const results = [];
+    for (const approver of new Set(approversById.values())) {
+        const sessionId = sessionByApprover.get(approver);
+        for (const approval of approver.list()) {
+            if (filter?.agent && approval.scope.agent !== filter.agent)
+                continue;
+            if (filter?.sessionId && sessionId !== filter.sessionId)
+                continue;
+            results.push(approval);
+        }
+    }
+    return results;
+}
+/** Routes to whichever WebchatApprover instance actually owns `id` — the
+ * caller doesn't need to know which turn/session created it. */
+export function decideApproval(id, approved) {
+    const approver = approversById.get(id);
+    if (!approver)
+        return false;
+    return approver.decide(id, approved);
+}
+/** Peek at a pending approval's own entry and owning session, without
+ * deciding it — adapters/http.ts needs this *before* calling
+ * decideApproval() above, to know which turn's early-return race (see its
+ * own sessionTurns) to resume once this one's decided. */
+export function findApproval(id) {
+    const approver = approversById.get(id);
+    if (!approver)
+        return undefined;
+    const approval = approver.list().find((a) => a.id === id);
+    if (!approval)
+        return undefined;
+    const sessionId = sessionByApprover.get(approver);
+    if (sessionId === undefined)
+        return undefined;
+    return { approval, sessionId };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopengine",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "Runtime for tool-using AI agents with a transparent ReAct loop.",
   "license": "MIT",
@@ -58,6 +58,9 @@
     "dist/core/http-notify-triggers",
     "dist/core/system-tools",
     "dist/core/system-skills",
+    "dist/core/durable-approvals.js",
+    "dist/core/durable-approvals.d.ts",
+    "dist/web",
     "protocol/loop-event.schema.json",
     "PROTOCOL.md",
     "LICENSE"
@@ -77,12 +80,12 @@
     "sessionknit": "^0.0.2",
     "skillgarden": "^0.0.5",
     "toollane": "^0.0.1",
+    "typescript": "^5.7.0",
     "yaml": "^2.6.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
     "tsx": "^4.19.0",
-    "typescript": "^5.7.0",
     "vitest": "^2.1.9"
   }
 }