create-loopengine 0.1.51 → 0.1.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-loopengine",
-  "version": "0.1.51",
+  "version": "0.1.53",
   "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/_gitignore

@@ -1,6 +1,7 @@
 node_modules
 dist
 .sessions
+.checkpoints
 .env
 *.log
 .DS_Store

package/template/adapters/http.ts

@@ -100,6 +100,16 @@ import {
   agentDirFor,
   verifyProxyIdentity,
   TRUSTED_PROXY_IDENTITY_HEADER,
+  NotifierFileError,
+  verifyDecisionToken,
+  renderDecidePage,
+  renderDecideGonePage,
+  renderDecideInvalidPage,
+  describeAgentNotifier,
+  listAgentPending,
+  removeAgentNotifier,
+  saveAgentNotifier,
+  testAgentNotifier,
   EnvVarNameError,
   readActauthConfig,
   addActauthRule,
@@ -178,6 +188,11 @@ const defaultHttpWebhookNotifier =
   defaultHttpWebhookUrl && defaultHttpWebhookSecret
     ? new WebhookNotifier({ webhookUrl: defaultHttpWebhookUrl, signingSecret: defaultHttpWebhookSecret })
     : undefined
+// The same default, as plain settings, for the console's Approvals
+// section (web/notifier-admin.ts) to show and test.
+const defaultWebhook =
+  defaultHttpWebhookUrl && defaultHttpWebhookSecret ? { webhookUrl: defaultHttpWebhookUrl, webhookSecret: defaultHttpWebhookSecret } : undefined
+
 
 // Used when an AgentConfig doesn't define its own sessionIdFor — a plain
 // client-supplied key, same shape adapters/cli.ts's --session flag
@@ -1034,6 +1049,76 @@ function handleEnvGet(res: ServerResponse, agentName: string): void {
   res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify(listDeclaredEnvVars(agentName)))
 }
 
+// Backs the console's Permissions tab (where approval requests and questions are sent) — see
+// web/notifier-admin.ts. Reading is open like the rest of the admin
+// surface; saving or removing writes a secret and a file, so it gets the
+// same refuse-without-auth gate as the env routes below.
+function handleNotifierGet(res: ServerResponse, agentName: string): void {
+  const entry = getEntry(agentName)
+  if (!entry) {
+    res.writeHead(404, { 'content-type': 'application/json' }).end(JSON.stringify({ error: `unknown agent '${agentName}'` }))
+    return
+  }
+  res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ ...describeAgentNotifier(entry.config, defaultWebhook), canSave: secretsProtected }))
+}
+
+async function handleNotifierPut(req: IncomingMessage, res: ServerResponse, agentName: string): Promise<void> {
+  if (!secretsProtected) {
+    res.writeHead(403, { 'content-type': 'application/json' }).end(
+      JSON.stringify({ error: 'Refusing to save a notifier without LOOPENGINE_ADMIN_AUTH configured — set it first, since this stores a secret.' }),
+    )
+    return
+  }
+  const entry = getEntry(agentName)
+  if (!entry) {
+    res.writeHead(404, { 'content-type': 'application/json' }).end(JSON.stringify({ error: `unknown agent '${agentName}'` }))
+    return
+  }
+  try {
+    await saveAgentNotifier(entry.config, await readJsonBody(req))
+  } catch (err) {
+    const status = err instanceof NotifierFileError ? 400 : 500
+    res.writeHead(status, { 'content-type': 'application/json' }).end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }))
+    return
+  }
+  res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ ...describeAgentNotifier(entry.config, defaultWebhook), canSave: secretsProtected }))
+}
+
+function handleNotifierDelete(res: ServerResponse, agentName: string): void {
+  if (!secretsProtected) {
+    res.writeHead(403, { 'content-type': 'application/json' }).end(
+      JSON.stringify({ error: 'Refusing to remove a notifier without LOOPENGINE_ADMIN_AUTH configured.' }),
+    )
+    return
+  }
+  const entry = getEntry(agentName)
+  if (!entry) {
+    res.writeHead(404, { 'content-type': 'application/json' }).end(JSON.stringify({ error: `unknown agent '${agentName}'` }))
+    return
+  }
+  removeAgentNotifier(entry.config)
+  res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ ...describeAgentNotifier(entry.config, defaultWebhook), canSave: secretsProtected }))
+}
+
+async function handleNotifierTest(res: ServerResponse, agentName: string): Promise<void> {
+  const entry = getEntry(agentName)
+  if (!entry) {
+    res.writeHead(404, { 'content-type': 'application/json' }).end(JSON.stringify({ error: `unknown agent '${agentName}'` }))
+    return
+  }
+  res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify(await testAgentNotifier(entry.config, defaultWebhook)))
+}
+
+// Every approval/question still waiting for this agent — for an app that
+// can't receive webhooks (it polls this instead) and for the console.
+async function handlePendingGet(res: ServerResponse, agentName: string): Promise<void> {
+  if (!getEntry(agentName)) {
+    res.writeHead(404, { 'content-type': 'application/json' }).end(JSON.stringify({ error: `unknown agent '${agentName}'` }))
+    return
+  }
+  res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ pending: await listAgentPending(checkpoints, agentName) }))
+}
+
 // `?slot=agent` targets this agent's own agents/<name>/.env (a per-agent
 // value, read by its tools through ToolContext.env) instead of the
 // project-wide .env — see loopengine's DeclaredEnvVar.slot.
@@ -1485,7 +1570,25 @@ async function handleSessionGet(req: IncomingMessage, res: ServerResponse, agent
 }
 
 type PendingSignal = { type: 'question'; entry: PendingQuestion } | { type: 'approval'; entry: PendingApproval }
-type FinishedTurn = { text: string; stopReason?: 'max_turns' | 'denied' | 'pending_approval' | 'pending_question' }
+type FinishedTurn = { text: string; stopReason?: 'max_turns' | 'denied' | 'pending_approval' | 'pending_question'; pending?: PendingSummary[] }
+
+// What a caller needs to act on a turn that paused for a durable
+// decision: which decision, and where to send it — the same pendingId and
+// path the notifier's webhook carries, so an app can resolve straight
+// from this response instead of waiting for the webhook or polling.
+type PendingSummary = { pendingId: string; kind: 'approval' | 'question'; tool: string; args: Record<string, unknown>; reason: string; resolvePath?: string; answerPath?: string }
+
+function pendingSummary(pending: RunAgentResult['pending']): PendingSummary[] | undefined {
+  if (!pending?.outstanding.length) return undefined
+  return pending.outstanding.map((item) => ({
+    pendingId: item.pendingId,
+    kind: item.kind,
+    tool: item.tool,
+    args: item.args,
+    reason: item.reason,
+    ...(item.kind === 'question' ? { answerPath: `/pending-questions/${item.pendingId}/answer` } : { resolvePath: `/pending-approvals/${item.pendingId}/resolve` }),
+  }))
+}
 
 // One entry per turn currently in flight for the plain (non-streaming)
 // /messages route, keyed by "<agentName>:<rawSessionId>" — the same
@@ -1621,6 +1724,7 @@ async function raceAndRespond(res: ServerResponse, agentName: string, rawSession
   // final-text summary of it.
   const responseBody: Record<string, unknown> = { text: winner.turnResult.text, sessionId: rawSessionId, events: state.events }
   if (winner.turnResult.stopReason) responseBody.stopReason = winner.turnResult.stopReason
+  if (winner.turnResult.pending) responseBody.pending = winner.turnResult.pending
   res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify(responseBody))
 }
 
@@ -1699,7 +1803,7 @@ async function handleMessages(req: IncomingMessage, res: ServerResponse, agentNa
     // raceAndRespond) always ends the same way regardless of which route
     // produced it.
     state.events.push({ type: 'done', text: result.text, ...(result.stopReason ? { stopReason: result.stopReason } : {}) })
-    return { newMessages: result.newMessages, result: { text: result.text, stopReason: result.stopReason } }
+    return { newMessages: result.newMessages, result: { text: result.text, stopReason: result.stopReason, pending: pendingSummary(result.pending) } }
   })
   state.turnPromise = turnPromise
 
@@ -1805,7 +1909,7 @@ async function handleMessagesStream(req: IncomingMessage, res: ServerResponse, a
     const doneEvent: LoopEvent = { type: 'done', text: result.text, ...(result.stopReason ? { stopReason: result.stopReason } : {}) }
     writeSseEvent(res, doneEvent)
     state.events.push(doneEvent)
-    return { newMessages: result.newMessages, result: { text: result.text, stopReason: result.stopReason } }
+    return { newMessages: result.newMessages, result: { text: result.text, stopReason: result.stopReason, pending: pendingSummary(result.pending) } }
   })
   state.turnPromise = turnPromise
 
@@ -1939,7 +2043,11 @@ async function createCheckpointFromPending(
  * response here is authoritative on its own, not a fallback for some
  * other channel. */
 async function handlePendingApprovalResolve(req: IncomingMessage, res: ServerResponse, pendingId: string): Promise<void> {
-  const body = await readJsonBody(req)
+  await resolvePendingApproval(res, pendingId, await readJsonBody(req))
+}
+
+// The resolve itself, shared with the decision page's POST /decide/<token>.
+async function resolvePendingApproval(res: ServerResponse, pendingId: string, body: Record<string, unknown>): Promise<void> {
   const decision = body.decision === 'approve' || body.decision === 'deny' ? body.decision : undefined
   if (!decision) {
     res.writeHead(400, { 'content-type': 'application/json' }).end(JSON.stringify({ error: "decision must be 'approve' or 'deny'" }))
@@ -2051,7 +2159,10 @@ async function handlePendingApprovalResolve(req: IncomingMessage, res: ServerRes
  * either answered or it isn't. Shares the same "outstanding empty →
  * resume, else report remaining count" tail via respondAfterResolution. */
 async function handlePendingQuestionAnswer(req: IncomingMessage, res: ServerResponse, pendingId: string): Promise<void> {
-  const body = await readJsonBody(req)
+  await answerPendingQuestion(res, pendingId, await readJsonBody(req))
+}
+
+async function answerPendingQuestion(res: ServerResponse, pendingId: string, body: Record<string, unknown>): Promise<void> {
   if (typeof body.answer !== 'string') {
     res.writeHead(400, { 'content-type': 'application/json' }).end(JSON.stringify({ error: "'answer' must be a string" }))
     return
@@ -2147,11 +2258,11 @@ async function respondAfterResolution(res: ServerResponse, finalCheckpoint: Turn
     if (result.pending) {
       await createCheckpointFromPending(finalCheckpoint.agent, finalCheckpoint.tenant, finalCheckpoint.sessionId, result.pending)
     }
-    return { newMessages: result.newMessages, result: { text: result.text, stopReason: result.stopReason } }
+    return { newMessages: result.newMessages, result: { text: result.text, stopReason: result.stopReason, pending: pendingSummary(result.pending) } }
   })
 
   res.writeHead(200, { 'content-type': 'application/json' }).end(
-    JSON.stringify({ text: responseBody.text, sessionId: finalCheckpoint.sessionId, ...(responseBody.stopReason ? { stopReason: responseBody.stopReason } : {}) }),
+    JSON.stringify({ text: responseBody.text, sessionId: finalCheckpoint.sessionId, ...(responseBody.stopReason ? { stopReason: responseBody.stopReason } : {}), ...(responseBody.pending ? { pending: responseBody.pending } : {}) }),
   )
 }
 
@@ -2337,7 +2448,59 @@ function handleActivityGet(res: ServerResponse): void {
   )
 }
 
+// A decision link (loopengine's core/approval-links.ts): GET shows the decision page,
+// POST makes the decision. The signed token is the credential, so these
+// sit outside the admin login on purpose — the link is meant for
+// whoever gets the notification, not only admins.
+async function handleDecide(req: IncomingMessage, res: ServerResponse, rawToken: string): Promise<void> {
+  const html = { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'referrer-policy': 'no-referrer' }
+  const json = { 'content-type': 'application/json', 'cache-control': 'no-store' }
+  const token = verifyDecisionToken(rawToken)
+  if (!token) {
+    if (req.method === 'GET') res.writeHead(404, html).end(renderDecideInvalidPage())
+    else res.writeHead(400, json).end(JSON.stringify({ error: 'This link is not valid or has expired.' }))
+    return
+  }
+  const checkpoint = await checkpoints.get(token.pendingId)
+  const item = checkpoint?.outstanding[token.pendingId]
+  if (!checkpoint || !item || (item.kind ?? 'approval') !== token.kind) {
+    if (req.method === 'GET') res.writeHead(410, html).end(renderDecideGonePage())
+    else res.writeHead(410, json).end(JSON.stringify({ error: 'This decision has already been made.' }))
+    return
+  }
+  if (req.method === 'GET') {
+    res.writeHead(200, html).end(
+      renderDecidePage({
+        kind: token.kind,
+        agent: checkpoint.agent,
+        tool: item.tool,
+        args: item.args,
+        reason: item.reason,
+        sessionId: checkpoint.sessionId,
+        tenant: checkpoint.tenant,
+        createdAt: checkpoint.createdAt,
+        expiresAt: token.expiresAt,
+      }),
+    )
+    return
+  }
+  const body = await readJsonBody(req)
+  if (token.kind === 'question') await answerPendingQuestion(res, token.pendingId, { answer: body.answer })
+  else await resolvePendingApproval(res, token.pendingId, { decision: body.decision, editedArgs: body.editedArgs })
+}
+
 const server = createServer(async (req, res) => {
+  const decideMatch = (req.method === 'GET' || req.method === 'POST') && (req.url ?? '/').split('?')[0].match(/^\/decide\/([A-Za-z0-9_.-]+)$/)
+  if (decideMatch) {
+    try {
+      await handleDecide(req, res, decideMatch[1])
+    } catch (err) {
+      console.error('[loopengine] decision link failed:', err)
+      if (!res.headersSent) res.writeHead(500, { 'content-type': 'application/json' }).end(JSON.stringify({ error: 'Something went wrong; try again.' }))
+    }
+    return
+  }
+
   if (!isAuthorized(req)) {
     const headers: Record<string, string> = { 'content-type': 'application/json' }
     if (adminAuth) headers['www-authenticate'] = 'Basic realm="loopengine"'
@@ -2713,6 +2876,32 @@ const server = createServer(async (req, res) => {
       return
     }
 
+    // Backs the console's Approvals section and polling clients — see
+    // handleNotifierGet/handlePendingGet above.
+    const notifierMatch = pathname.match(/^\/agents\/([^/]+)\/notifier$/)
+    if (notifierMatch && req.method === 'GET') {
+      handleNotifierGet(res, decodeURIComponent(notifierMatch[1]))
+      return
+    }
+    if (notifierMatch && req.method === 'PUT') {
+      await handleNotifierPut(req, res, decodeURIComponent(notifierMatch[1]))
+      return
+    }
+    if (notifierMatch && req.method === 'DELETE') {
+      handleNotifierDelete(res, decodeURIComponent(notifierMatch[1]))
+      return
+    }
+    const notifierTestMatch = req.method === 'POST' && pathname.match(/^\/agents\/([^/]+)\/notifier\/test$/)
+    if (notifierTestMatch) {
+      await handleNotifierTest(res, decodeURIComponent(notifierTestMatch[1]))
+      return
+    }
+    const pendingListMatch = req.method === 'GET' && pathname.match(/^\/agents\/([^/]+)\/pending$/)
+    if (pendingListMatch) {
+      await handlePendingGet(res, decodeURIComponent(pendingListMatch[1]))
+      return
+    }
+
     // Backs the Admin UI's "Environment" section — see
     // handleEnvGet/handleEnvPut's own doc comments above.
     const envListMatch = pathname.match(/^\/agents\/([^/]+)\/env$/)

package/template/package.json

@@ -9,7 +9,7 @@
     "cli": "tsx adapters/cli.ts"
   },
   "dependencies": {
-    "loopengine": "^0.1.63",
+    "loopengine": "^0.1.68",
     "actauth": "^0.0.12"
   },
   "devDependencies": {