create-loopengine 0.1.53 → 0.1.55

package/package.json

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

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

package/template/adapters/http.ts

@@ -106,7 +106,29 @@ import {
   renderDecideGonePage,
   renderDecideInvalidPage,
   describeAgentNotifier,
+  announceToNotifier,
+  Scheduler,
+  ScheduleError,
+  cancelScheduledTask,
+  createScheduledTask,
+  deleteScheduledTask,
+  describeSchedule,
+  getScheduledTask,
+  listScheduledTasks,
+  nextScheduledWakeAt,
+  pauseScheduledTask,
+  resumeScheduledTask,
+  runScheduledTaskNow,
+  type ScheduledTask,
+  type ScheduledTaskRun,
   listAgentPending,
+  listAgentSlackChannels,
+  slackCredentialsFor,
+  openSlackAnswerModal,
+  parseSlackInteraction,
+  replyInSlack,
+  slackOutcomeText,
+  verifySlackRequest,
   removeAgentNotifier,
   saveAgentNotifier,
   testAgentNotifier,
@@ -150,6 +172,7 @@ import {
   resolvePendingQuestion as answerQuestion,
   findQuestion,
   createAskUserTool,
+  createScheduleTools,
   type PendingQuestion,
   WebhookNotifier,
 } from 'loopengine'
@@ -239,6 +262,15 @@ function resolveTenant(
   return result === undefined ? { ok: false } : { ok: true, value: result }
 }
 
+function readRawBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let data = ''
+    req.on('data', (chunk) => (data += chunk))
+    req.on('end', () => resolve(data))
+    req.on('error', reject)
+  })
+}
+
 function readJsonBody(req: IncomingMessage): Promise<Record<string, unknown>> {
   return new Promise((resolve, reject) => {
     let data = ''
@@ -407,7 +439,7 @@ async function describeAgent(entry: RegistryEntry): Promise<Record<string, unkno
     // createAskUserTool() with no onPending, purely to describe its
     // schema here — never executed, so the console-prompt fallback its
     // own doc comment mentions never applies to this call.
-    systemTools: [...systemTools, createAskUserTool({ agent: config.name })].map(describeTool),
+    systemTools: [...systemTools, createAskUserTool({ agent: config.name }), ...(config.selfScheduling === false ? [] : createScheduleTools(config.name))].map(describeTool),
     localTools: localTools.map((t) => ({ ...describeTool(t), httpToolEditable: editableHttpToolNames.has(t.name) })),
     agentAsTools: agentAsTools.map(describeTool),
     gatewayTools: gatewayTools.map(describeTool),
@@ -1049,6 +1081,92 @@ function handleEnvGet(res: ServerResponse, agentName: string): void {
   res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify(listDeclaredEnvVars(agentName)))
 }
 
+// ---- Scheduled tasks (loopengine's core/scheduler.ts). A task fires through the same
+// path as a plain POST /agents/:name/messages: the session is kept, an
+// "ask" goes to the agent's notifier (or the default webhook) as a
+// durable approval, and with no notifier at all it's denied rather than
+// left waiting on nobody — a scheduled run has no one live in it. ----
+
+const NO_HUMAN_ANSWER = 'No human is available to answer — this is an unattended scheduled run. Use your own best judgement and proceed without waiting for a response.'
+
+async function fireScheduledTask(task: ScheduledTask, rawSessionId: string): Promise<{ kind: 'done'; text: string } | { kind: 'pending'; pendingIds: string[] }> {
+  const entry = getEntry(task.agent)
+  if (!entry) throw new Error(`no agent named "${task.agent}" in this project`)
+  const tenant = 'default'
+  const environment = process.env.LOOPENGINE_ENV ?? 'production'
+  const outcome = await sessions.withSession(`${tenant}:${environment}:${task.agent}:${rawSessionId}`, async (history) => {
+    const result = await runAgent(entry.config, entry.createModelCall(), task.message, history, {
+      tenant,
+      sessionId: rawSessionId,
+      channel: 'http',
+      approver: defaultHttpWebhookNotifier ?? { requestApproval: async () => false },
+      questionHandler: defaultHttpWebhookNotifier ?? { requestQuestion: async () => NO_HUMAN_ANSWER },
+    })
+    if (result.pending) await createCheckpointFromPending(task.agent, tenant, rawSessionId, result.pending)
+    return { newMessages: result.newMessages, result: { text: result.text, stopReason: result.stopReason, pendingIds: result.pending?.outstanding.map((o) => o.pendingId) } }
+  })
+  if (outcome.pendingIds?.length) return { kind: 'pending', pendingIds: outcome.pendingIds }
+  // run-agent's "you denied" wording is for someone live in a chat; in a
+  // scheduled run nobody denied anything, so say what actually happened.
+  if (outcome.stopReason === 'denied') {
+    const tools = /denied: (.+?)\. Send/.exec(outcome.text)?.[1] ?? 'a tool call'
+    throw new Error(`Not allowed: ${tools}. A call that needs approval is denied in a scheduled run unless the Permissions tab sends approval requests somewhere (or a rule denies it outright).`)
+  }
+  return { kind: 'done', text: outcome.text }
+}
+
+// A task with `notify` on reports each run through its agent's notifier.
+function announceScheduledRun(task: ScheduledTask, run: ScheduledTaskRun): void {
+  if (!task.notify) return
+  const entry = getEntry(task.agent)
+  if (!entry) return
+  const label = task.task_name ? `"${task.task_name}"` : `(${describeSchedule(task.schedule)})`
+  const text = run.status === 'ok' ? `Scheduled task ${label} for ${task.agent} ran:\n${run.result ?? ''}` : `Scheduled task ${label} for ${task.agent} failed: ${run.error ?? 'unknown error'}`
+  announceToNotifier(entry.config, text, { scheduledTaskId: task.task_id, taskName: task.task_name ?? null, status: run.status, result: run.result ?? null, error: run.error ?? null }, defaultWebhook)
+}
+
+const scheduler = new Scheduler({ fire: fireScheduledTask, onSettled: announceScheduledRun })
+
+function scheduleJson(res: ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, { 'content-type': 'application/json' }).end(JSON.stringify(body))
+}
+
+async function handleSchedulesGet(res: ServerResponse, agentName: string): Promise<void> {
+  if (!getEntry(agentName)) return scheduleJson(res, 404, { error: `unknown agent '${agentName}'` })
+  scheduleJson(res, 200, { tasks: await listScheduledTasks({ agent: agentName }) })
+}
+
+async function handleSchedulesPost(req: IncomingMessage, res: ServerResponse, agentName: string): Promise<void> {
+  if (!getEntry(agentName)) return scheduleJson(res, 404, { error: `unknown agent '${agentName}'` })
+  const body = await readJsonBody(req)
+  try {
+    const task = await createScheduledTask({
+      agent: agentName,
+      message: String(body.message ?? ''),
+      schedule: (body.schedule ?? {}) as { run_at?: unknown; every?: unknown },
+      task_name: typeof body.task_name === 'string' ? body.task_name : undefined,
+      notify: body.notify === true,
+    })
+    scheduleJson(res, 201, task)
+  } catch (err) {
+    scheduleJson(res, err instanceof ScheduleError ? 400 : 500, { error: err instanceof Error ? err.message : String(err) })
+  }
+}
+
+async function handleScheduleAction(res: ServerResponse, taskId: string, action: string): Promise<void> {
+  try {
+    if (action === 'run') await runScheduledTaskNow(taskId)
+    else if (action === 'pause') await pauseScheduledTask(taskId)
+    else if (action === 'resume') await resumeScheduledTask(taskId)
+    else if (action === 'cancel') await cancelScheduledTask(taskId)
+    else return scheduleJson(res, 404, { error: `unknown action '${action}'` })
+    if (action === 'run') void scheduler.tick()
+    scheduleJson(res, 200, await getScheduledTask(taskId))
+  } catch (err) {
+    scheduleJson(res, err instanceof ScheduleError ? 404 : 500, { error: err instanceof Error ? err.message : String(err) })
+  }
+}
+
 // 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
@@ -1109,6 +1227,23 @@ async function handleNotifierTest(res: ServerResponse, agentName: string): Promi
   res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify(await testAgentNotifier(entry.config, defaultWebhook)))
 }
 
+// Backs the console's Slack channel picker. A bot token typed into the form
+// (not saved yet) can be sent in the body; otherwise the saved one is used.
+async function handleSlackChannels(req: IncomingMessage, 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
+  }
+  const body = await readJsonBody(req)
+  try {
+    const channels = await listAgentSlackChannels(entry.config, typeof body.botToken === 'string' ? body.botToken : undefined)
+    res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ channels }))
+  } catch (err) {
+    res.writeHead(400, { 'content-type': 'application/json' }).end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }))
+  }
+}
+
 // 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> {
@@ -2261,6 +2396,10 @@ async function respondAfterResolution(res: ServerResponse, finalCheckpoint: Turn
     return { newMessages: result.newMessages, result: { text: result.text, stopReason: result.stopReason, pending: pendingSummary(result.pending) } }
   })
 
+  // A scheduled task's paused run (core/scheduler.ts) settles here.
+  void scheduler
+    .settleFromResume(finalCheckpoint.sessionId, { text: responseBody.text, pendingIds: responseBody.pending?.map((p) => p.pendingId) })
+    .catch((err) => console.error('[loopengine] could not settle scheduled run:', err))
   res.writeHead(200, { 'content-type': 'application/json' }).end(
     JSON.stringify({ text: responseBody.text, sessionId: finalCheckpoint.sessionId, ...(responseBody.stopReason ? { stopReason: responseBody.stopReason } : {}), ...(responseBody.pending ? { pending: responseBody.pending } : {}) }),
   )
@@ -2437,10 +2576,14 @@ function exitIfCodeChanged(res: ServerResponse): void {
 let openStreams = 0
 let lastRequestAt = Date.now()
 
-function handleActivityGet(res: ServerResponse): void {
+async function handleActivityGet(res: ServerResponse): Promise<void> {
   res.writeHead(200, { 'content-type': 'application/json' }).end(
     JSON.stringify({
-      inFlightTurns: sessionTurns.size,
+      inFlightTurns: sessionTurns.size + scheduler.running,
+      scheduledRuns: scheduler.running,
+      // When the next scheduled task is due — wake this server by then
+      // (POST /internal/scheduler/tick) if it's been stopped while idle.
+      nextWakeAt: (await nextScheduledWakeAt()) ?? null,
       openStreams,
       lastRequestAt: new Date(lastRequestAt).toISOString(),
       idleSeconds: Math.floor((Date.now() - lastRequestAt) / 1000),
@@ -2489,7 +2632,82 @@ async function handleDecide(req: IncomingMessage, res: ServerResponse, rawToken:
   else await resolvePendingApproval(res, token.pendingId, { decision: body.decision, editedArgs: body.editedArgs })
 }
 
+// Runs one of the resolve/answer handlers above without a real HTTP
+// response to write to — for the Slack endpoint below, which has already
+// answered Slack and reports the outcome back into the Slack message.
+function captureResponse(): { res: ServerResponse; done: Promise<{ status: number; body: Record<string, unknown> }> } {
+  let resolveDone: (value: { status: number; body: Record<string, unknown> }) => void
+  const done = new Promise<{ status: number; body: Record<string, unknown> }>((resolve) => (resolveDone = resolve))
+  let status = 200
+  const res = {
+    headersSent: false,
+    writeHead(code: number) {
+      status = code
+      return res
+    },
+    end(chunk?: string) {
+      let body: Record<string, unknown> = {}
+      try {
+        body = chunk ? (JSON.parse(chunk) as Record<string, unknown>) : {}
+      } catch {}
+      resolveDone({ status, body })
+      return res
+    },
+  }
+  return { res: res as unknown as ServerResponse, done }
+}
+
+// A Slack app's Interactivity Request URL (core/slack-interactions.ts):
+// Approve/Deny, an answer option, or the "Other…" modal, from a Slack
+// notifier's message. Outside the admin login on purpose — Slack can't
+// send it — and verified with that agent's Slack signing secret instead.
+// Slack wants an answer within three seconds, so the decision is acked
+// right away and its outcome posted back into the message afterwards.
+async function handleSlackInteraction(req: IncomingMessage, res: ServerResponse, agentName: string): Promise<void> {
+  const rawBody = await readRawBody(req)
+  const entry = getEntry(agentName)
+  const { botToken, signingSecret } = entry ? slackCredentialsFor(entry.config) : {}
+  if (!entry || !signingSecret) {
+    res.writeHead(404, { 'content-type': 'text/plain' }).end('No Slack signing secret is set for this agent.')
+    return
+  }
+  const timestamp = req.headers['x-slack-request-timestamp']
+  const signature = req.headers['x-slack-signature']
+  if (!verifySlackRequest(rawBody, typeof timestamp === 'string' ? timestamp : undefined, typeof signature === 'string' ? signature : undefined, signingSecret)) {
+    res.writeHead(401, { 'content-type': 'text/plain' }).end('Invalid Slack signature.')
+    return
+  }
+  const interaction = parseSlackInteraction(rawBody)
+  if (interaction.type === 'open_answer') {
+    if (botToken) await openSlackAnswerModal(botToken, interaction.triggerId, interaction.pendingId).catch((err) => console.error('[loopengine] Slack modal failed:', err))
+    res.writeHead(200).end()
+    return
+  }
+  res.writeHead(200).end()
+  if (interaction.type === 'ignore') return
+
+  const capture = captureResponse()
+  if (interaction.type === 'decide') await resolvePendingApproval(capture.res, interaction.pendingId, { decision: interaction.decision })
+  else await answerPendingQuestion(capture.res, interaction.pendingId, { answer: interaction.answer })
+  const outcome = await capture.done
+  if (interaction.responseUrl) {
+    const text = slackOutcomeText(interaction.type === 'decide' ? interaction.decision : 'answer', outcome.status, outcome.body, interaction.user)
+    await replyInSlack(interaction.responseUrl, text).catch((err) => console.error('[loopengine] Slack reply failed:', err))
+  }
+}
+
 const server = createServer(async (req, res) => {
+  const slackHookMatch = req.method === 'POST' && (req.url ?? '/').split('?')[0].match(/^\/hooks\/slack\/([^/]+)$/)
+  if (slackHookMatch) {
+    try {
+      await handleSlackInteraction(req, res, decodeURIComponent(slackHookMatch[1]))
+    } catch (err) {
+      console.error('[loopengine] Slack interaction failed:', err)
+      if (!res.headersSent) res.writeHead(500).end()
+    }
+    return
+  }
+
   const decideMatch = (req.method === 'GET' || req.method === 'POST') && (req.url ?? '/').split('?')[0].match(/^\/decide\/([A-Za-z0-9_.-]+)$/)
   if (decideMatch) {
     try {
@@ -2527,9 +2745,15 @@ const server = createServer(async (req, res) => {
     // Only exists in trusted-proxy mode, and polling it doesn't count as
     // activity itself.
     if (trustedProxySecret && req.method === 'GET' && pathname === '/internal/activity') {
-      handleActivityGet(res)
+      await handleActivityGet(res)
+      return
+    }
+    // A host waking this server for a due task: fire whatever is due now.
+    if (trustedProxySecret && req.method === 'POST' && pathname === '/internal/scheduler/tick') {
+      res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ fired: await scheduler.tick() }))
       return
     }
+
     lastRequestAt = Date.now()
 
     const streamMatch = req.method === 'POST' && pathname.match(/^\/agents\/([^/]+)\/messages\/stream$/)
@@ -2896,6 +3120,33 @@ const server = createServer(async (req, res) => {
       await handleNotifierTest(res, decodeURIComponent(notifierTestMatch[1]))
       return
     }
+    // Backs the console's Schedules tab — see handleSchedulesGet above.
+    const schedulesMatch = pathname.match(/^\/agents\/([^/]+)\/schedules$/)
+    if (schedulesMatch && req.method === 'GET') {
+      await handleSchedulesGet(res, decodeURIComponent(schedulesMatch[1]))
+      return
+    }
+    if (schedulesMatch && req.method === 'POST') {
+      await handleSchedulesPost(req, res, decodeURIComponent(schedulesMatch[1]))
+      return
+    }
+    const scheduleActionMatch = req.method === 'POST' && pathname.match(/^\/schedules\/([A-Za-z0-9_-]+)\/(run|pause|resume|cancel)$/)
+    if (scheduleActionMatch) {
+      await handleScheduleAction(res, scheduleActionMatch[1], scheduleActionMatch[2])
+      return
+    }
+    const scheduleDeleteMatch = req.method === 'DELETE' && pathname.match(/^\/schedules\/([A-Za-z0-9_-]+)$/)
+    if (scheduleDeleteMatch) {
+      await deleteScheduledTask(scheduleDeleteMatch[1])
+      scheduleJson(res, 200, { ok: true })
+      return
+    }
+
+    const slackChannelsMatch = req.method === 'POST' && pathname.match(/^\/agents\/([^/]+)\/notifier\/slack-channels$/)
+    if (slackChannelsMatch) {
+      await handleSlackChannels(req, res, decodeURIComponent(slackChannelsMatch[1]))
+      return
+    }
     const pendingListMatch = req.method === 'GET' && pathname.match(/^\/agents\/([^/]+)\/pending$/)
     if (pendingListMatch) {
       await handlePendingGet(res, decodeURIComponent(pendingListMatch[1]))
@@ -3029,7 +3280,31 @@ const server = createServer(async (req, res) => {
 })
 
 const port = Number(process.env.PORT ?? 8787)
-server.listen(port, () => console.log(`agent API listening on :${port}`))
+server.listen(port, () => {
+  console.log(`agent API listening on :${port}`)
+  void warmAgentTools()
+  // LOOPENGINE_SCHEDULER=off leaves scheduling to another process.
+  if (process.env.LOOPENGINE_SCHEDULER !== 'off') void scheduler.start().catch((err) => console.error('[loopengine] scheduler failed to start:', err))
+})
+
+// An agent that leaves `tools` unset gets its tools/ folder imported
+// lazily, on its first turn. Importing every agent's tools (and
+// subagents) right at startup instead means anything an ability's tool
+// file starts on load — a background timer, say — runs from boot, not
+// only after someone first talks to that agent. A broken tool file is
+// logged and skipped; its agent still fails loudly on its own first turn.
+async function warmAgentTools(): Promise<void> {
+  for (const name of listAgents()) {
+    const entry = getEntry(name)
+    if (!entry) continue
+    try {
+      if (entry.config.tools === undefined) await loadDefaultTools(entry.config)
+      await loadSubagentAsTools(entry.config)
+    } catch (err) {
+      console.error(`[loopengine] could not load tools for agent '${name}' at startup:`, err instanceof Error ? err.message : err)
+    }
+  }
+}
 
 // server.close() alone only stops accepting *new* connections — it
 // doesn't wait for existing ones, and the old code called process.exit
@@ -3059,6 +3334,7 @@ server.listen(port, () => console.log(`agent API listening on :${port}`))
 // process restart, just this one process's own event loop.
 async function shutdown() {
   console.log('[loopengine] shutting down — draining in-flight requests...')
+  scheduler.stop()
   const graceMs = Number(process.env.LOOPENGINE_SHUTDOWN_GRACE_MS ?? 30000)
   const closed = new Promise<void>((resolve) => server.close(() => resolve()))
   // HTTP keep-alive means a connection whose last request already

package/template/package.json

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