backeer-opencode 0.2.3 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backeer-opencode",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Backeer lifecycle notifications and remote permission decisions for OpenCode",
   "type": "module",
   "main": "./src/index.js",
@@ -20,7 +20,8 @@
   ],
   "scripts": {
     "build": "esbuild src/index.js --bundle --platform=node --format=esm --target=node18 --outfile=dist/backeer-permission.js --legal-comments=none",
-    "check": "node --check bin/backeer-opencode.js && npm test",
+    "check": "npm run lint && node --check bin/backeer-opencode.js && npm test",
+    "lint": "eslint src bin test eslint.config.js --max-warnings=0",
     "pretest": "npm run build",
     "test": "node --test",
     "pack:check": "npm pack --dry-run",
@@ -50,7 +51,10 @@
     "access": "public"
   },
   "devDependencies": {
-    "esbuild": "^0.28.2"
+    "@eslint/js": "^9.39.5",
+    "esbuild": "^0.28.2",
+    "eslint": "^9.39.5",
+    "globals": "^16.5.0"
   },
   "license": "SEE LICENSE IN LICENSE"
 }

package/src/delivery-tracker.js

@@ -0,0 +1,75 @@
+import { rememberBounded } from "./utilities.js"
+
+export function createDeliveryTracker() {
+  const states = new Map()
+
+  return {
+    begin(key) {
+      if (states.has(key)) return false
+      rememberBounded(states, key, "publishing")
+      return true
+    },
+
+    succeed(key) {
+      if (states.get(key) === "publishing") {
+        rememberBounded(states, key, "published")
+      }
+    },
+
+    fail(key) {
+      if (states.get(key) === "publishing") states.delete(key)
+    },
+
+    clear() {
+      states.clear()
+    },
+  }
+}
+
+export function createCompletionTracker() {
+  const states = new Map()
+
+  function stateFor(key) {
+    let state = states.get(key)
+    if (!state) {
+      state = { complete: false, publishing: false, revision: 0 }
+      rememberBounded(states, key, state)
+    }
+    return state
+  }
+
+  return {
+    update(key, complete) {
+      const state = stateFor(key)
+      if (!complete) {
+        state.complete = false
+        state.publishing = false
+        state.revision++
+        return
+      }
+      if (state.complete || state.publishing) return
+
+      state.publishing = true
+      state.revision++
+      return { key, revision: state.revision }
+    },
+
+    succeed(attempt) {
+      const state = states.get(attempt?.key)
+      if (!state || state.revision !== attempt.revision) return
+      state.complete = true
+      state.publishing = false
+    },
+
+    fail(attempt) {
+      const state = states.get(attempt?.key)
+      if (!state || state.revision !== attempt.revision) return
+      state.complete = false
+      state.publishing = false
+    },
+
+    clear() {
+      states.clear()
+    },
+  }
+}

package/src/feedback-session-store.js

@@ -0,0 +1,110 @@
+import { limit, rememberBounded } from "./utilities.js"
+
+const MAX_QUEUED_MESSAGES = 20
+
+export class FeedbackSessionStore {
+  constructor({ send, reporter }) {
+    this.send = send
+    this.reporter = reporter
+    this.sessions = new Map()
+    this.disposed = false
+  }
+
+  stateFor(sessionID) {
+    let state = this.sessions.get(sessionID)
+    if (!state) {
+      state = {
+        idle: false,
+        flushing: false,
+        blockers: new Set(),
+        queue: [],
+        queued: new Set(),
+        queueOverflowReported: false,
+      }
+      rememberBounded(this.sessions, sessionID, state)
+    }
+    return state
+  }
+
+  hasReadyMessage(state) {
+    return !this.disposed && state.idle &&
+      state.blockers.size === 0 && state.queue.length > 0
+  }
+
+  async flush(sessionID, state) {
+    if (state.flushing || !this.hasReadyMessage(state)) return
+    state.flushing = true
+    try {
+      while (this.hasReadyMessage(state)) {
+        const item = state.queue[0]
+        try {
+          await this.send(sessionID, item.kind, item.message)
+          state.queue.shift()
+          state.queued.delete(item.key)
+        } catch (error) {
+          state.idle = false
+          this.reporter.debug("Conversation feedback could not be displayed", error)
+        }
+      }
+    } finally {
+      state.flushing = false
+    }
+  }
+
+  enqueue(kind, sessionID, message) {
+    if (this.disposed || typeof sessionID !== "string" || !sessionID || !message) return
+    const state = this.stateFor(sessionID)
+    const key = `${sessionID}:${kind}:${message}`
+    if (state.queued.has(key)) return
+
+    state.queue.push({ kind, message: limit(message, 300), key })
+    state.queued.add(key)
+    if (state.queue.length > MAX_QUEUED_MESSAGES) {
+      const removed = state.queue.shift()
+      state.queued.delete(removed.key)
+      if (!state.queueOverflowReported) {
+        state.queueOverflowReported = true
+        this.reporter.warning("Conversation feedback queue full — oldest message discarded")
+      }
+    }
+    if (state.idle && state.blockers.size === 0) void this.flush(sessionID, state)
+  }
+
+  setIdle(sessionID, idle) {
+    if (typeof sessionID !== "string" || !sessionID) return
+    const state = this.stateFor(sessionID)
+    state.idle = idle
+    if (idle) void this.flush(sessionID, state)
+  }
+
+  beginInteraction(sessionID, key) {
+    const state = this.stateFor(sessionID)
+    state.idle = false
+    state.blockers.add(key)
+  }
+
+  endInteraction(sessionID, key, kind) {
+    const state = this.stateFor(sessionID)
+    if (!state.blockers.delete(key)) {
+      const fallback = [...state.blockers]
+        .find((blocker) => blocker.startsWith(`${kind}:`))
+      if (fallback) state.blockers.delete(fallback)
+    }
+    state.idle = false
+  }
+
+  failSession(sessionID) {
+    const state = this.stateFor(sessionID)
+    state.blockers.clear()
+    state.idle = false
+  }
+
+  delete(sessionID) {
+    this.sessions.delete(sessionID)
+  }
+
+  dispose() {
+    this.disposed = true
+    this.sessions.clear()
+  }
+}

package/src/lifecycle-publishers.js

@@ -1,6 +1,8 @@
 import { postJsonWithRetry } from "./http.js"
 import { limit, stableHash } from "./utilities.js"
 
+// Intentional sanitization of non-printable control bytes before logging.
+// eslint-disable-next-line no-control-regex
 const CONTROL_CHARACTERS = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g
 const SECRET_ASSIGNMENT = /\b(token|secret|password|api[-_ ]?key)\s*[:=]\s*[^\s,;]+/gi
 const BEARER_TOKEN = /\bBearer\s+[^\s,;]+/gi

package/src/permission-command.js

@@ -0,0 +1,60 @@
+import { HttpError } from "./http.js"
+
+export const ALLOWED_DECISIONS = new Set(["once", "always", "reject"])
+
+const DECISION_LABELS = {
+  once: "Allow once",
+  always: "Always allow",
+  reject: "Reject",
+}
+
+export function validatePermissionCommand(command, now = Date.now()) {
+  if (!ALLOWED_DECISIONS.has(command.decision)) {
+    return {
+      status: "rejected",
+      decision: command.decision,
+      errorCode: "invalid_decision",
+    }
+  }
+
+  const expiresAt = Date.parse(command.expiresAt)
+  if (!Number.isFinite(expiresAt) || expiresAt <= now) {
+    return { status: "expired", decision: command.decision }
+  }
+
+  if (command.decision === "always" && command.confirmed !== true) {
+    return {
+      status: "rejected",
+      decision: command.decision,
+      errorCode: "confirmation_required",
+    }
+  }
+}
+
+export function failureAcknowledgement(command, error) {
+  const stale = error instanceof HttpError && error.status === 404
+  return {
+    status: stale ? "stale" : "failed",
+    decision: command.decision,
+    errorCode: stale ? "permission_not_found" : "opencode_reply_failed",
+  }
+}
+
+export function reportAcknowledgement(acknowledgement, pending, reporter, conversation) {
+  const messages = {
+    applied: `Decision applied: ${DECISION_LABELS[acknowledgement.decision]}`,
+    expired: "Decision expired before it could be applied",
+    stale: "Permission was already answered locally",
+    rejected: "Decision was rejected by validation",
+  }
+  const message = messages[acknowledgement.status]
+  if (!message) return
+
+  if (acknowledgement.status === "applied") {
+    reporter.applied(message)
+    conversation?.applied(pending.sessionID, message)
+    return
+  }
+  reporter.warning(message)
+  conversation?.warning(pending.sessionID, message)
+}

package/src/permission-controller.js

@@ -1,14 +1,12 @@
 import { HttpError, postJsonWithRetry } from "./http.js"
+import {
+  failureAcknowledgement,
+  reportAcknowledgement,
+  validatePermissionCommand,
+} from "./permission-command.js"
 import { runCommandStream } from "./sse.js"
 import { rememberBounded } from "./utilities.js"
 
-const ALLOWED_DECISIONS = new Set(["once", "always", "reject"])
-const DECISION_LABELS = {
-  once: "Allow once",
-  always: "Always allow",
-  reject: "Reject",
-}
-
 async function replyToOpenCode(client, pending, decision) {
   const result = await client.postSessionIdPermissionsPermissionId({
     path: { id: pending.sessionID, permissionID: pending.requestID },
@@ -41,7 +39,6 @@ export function createPermissionController({
   const externalIDByRequestID = new Map()
   const processingCommands = new Set()
   const completedCommands = new Map()
-  const publishedPermissions = new Map()
   let commandStream
   let disposed = false
 
@@ -74,36 +71,18 @@ export function createPermissionController({
     if (!pending) return
 
     processingCommands.add(command.id)
-    let acknowledgement
+    let acknowledgement = validatePermissionCommand(command)
     try {
-      if (!ALLOWED_DECISIONS.has(command.decision)) {
-        acknowledgement = { status: "rejected", errorCode: "invalid_decision" }
-      } else {
-        const expiresAt = Date.parse(command.expiresAt)
-        if (!Number.isFinite(expiresAt) || expiresAt <= Date.now()) {
-          acknowledgement = { status: "expired", decision: command.decision }
-        } else if (command.decision === "always" && command.confirmed !== true) {
-          acknowledgement = {
-            status: "rejected",
-            decision: command.decision,
-            errorCode: "confirmation_required",
-          }
-        } else {
-          await replyToOpenCode(client, pending, command.decision)
-          acknowledgement = { status: "applied", decision: command.decision }
-          removePendingByRequestID(pending.requestID)
-        }
+      if (!acknowledgement) {
+        await replyToOpenCode(client, pending, command.decision)
+        acknowledgement = { status: "applied", decision: command.decision }
+        removePendingByRequestID(pending.requestID)
       }
     } catch (error) {
-      const stale = error instanceof HttpError && error.status === 404
-      acknowledgement = {
-        status: stale ? "stale" : "failed",
-        decision: ALLOWED_DECISIONS.has(command.decision)
-          ? command.decision
-          : undefined,
-        errorCode: stale ? "permission_not_found" : "opencode_reply_failed",
+      acknowledgement = failureAcknowledgement(command, error)
+      if (acknowledgement.status === "stale") {
+        removePendingByRequestID(pending.requestID)
       }
-      if (stale) removePendingByRequestID(pending.requestID)
       reporter.error("Decision could not be applied", error)
       conversation?.error(pending.sessionID, "Decision could not be applied")
     } finally {
@@ -118,24 +97,7 @@ export function createPermissionController({
     }
     rememberBounded(completedCommands, command.id, acknowledgement)
 
-    if (acknowledgement.status === "applied") {
-      reporter.applied(
-        `Decision applied: ${DECISION_LABELS[acknowledgement.decision]}`,
-      )
-      conversation?.applied(
-        pending.sessionID,
-        `Decision applied: ${DECISION_LABELS[acknowledgement.decision]}`,
-      )
-    } else if (acknowledgement.status === "expired") {
-      reporter.warning("Decision expired before it could be applied")
-      conversation?.warning(pending.sessionID, "Decision expired before it could be applied")
-    } else if (acknowledgement.status === "stale") {
-      reporter.warning("Permission was already answered locally")
-      conversation?.warning(pending.sessionID, "Permission was already answered locally")
-    } else if (acknowledgement.status === "rejected") {
-      reporter.warning("Decision was rejected by validation")
-      conversation?.warning(pending.sessionID, "Decision was rejected by validation")
-    }
+    reportAcknowledgement(acknowledgement, pending, reporter, conversation)
 
     await acknowledgeCommand(config, command.id, acknowledgement).catch((error) => {
       reporter.warning("Decision receipt could not be sent", error)
@@ -167,10 +129,6 @@ export function createPermissionController({
       pendingByExternalID.set(identity.externalId, { ...identity, directory })
       externalIDByRequestID.set(identity.requestID, identity.externalId)
       ensureCommandStream()
-
-      if (publishedPermissions.has(identity.externalId)) return false
-      rememberBounded(publishedPermissions, identity.externalId, true)
-      return true
     },
 
     resolveLocally(requestID) {
@@ -198,7 +156,6 @@ export function createPermissionController({
       externalIDByRequestID.clear()
       processingCommands.clear()
       completedCommands.clear()
-      publishedPermissions.clear()
     },
   }
 }

package/src/plugin.js

@@ -1,4 +1,8 @@
 import { loadConfig } from "./config.js"
+import {
+  createCompletionTracker,
+  createDeliveryTracker,
+} from "./delivery-tracker.js"
 import {
   permissionIdentity,
   publishPermission,
@@ -18,7 +22,6 @@ import {
   createUpdateChecker,
   createUpdateNoticeHook,
 } from "./updates.js"
-import { rememberBounded } from "./utilities.js"
 
 /**
  * OpenCode server plugin entrypoint.
@@ -58,8 +61,9 @@ export default async function BackeerPlugin({ client, directory }, options = {})
     directory,
     conversation,
   })
-  const todoCompletionBySessionID = new Map()
-  const publishedQuestions = new Map()
+  const permissionPublications = createDeliveryTracker()
+  const questionPublications = createDeliveryTracker()
+  const todoCompletions = createCompletionTracker()
   const updateChecker = createUpdateChecker()
   const handleBackeerCommand = createBackeerCommandHandler({
     client,
@@ -83,7 +87,8 @@ export default async function BackeerPlugin({ client, directory }, options = {})
       reporter.error("Permission event is missing correlation IDs")
       return
     }
-    if (!permissionController.register(identity)) return
+    permissionController.register(identity)
+    if (!permissionPublications.begin(identity.externalId)) return
 
     void publishPermission(
       config,
@@ -92,10 +97,12 @@ export default async function BackeerPlugin({ client, directory }, options = {})
       directory,
       identity,
       conversation,
-    ).catch((error) => {
-      reporter.error("Permission request could not be sent", error)
-      conversation.error(identity.sessionID, "Permission request could not be sent")
-    })
+    ).then(() => permissionPublications.succeed(identity.externalId))
+      .catch((error) => {
+        permissionPublications.fail(identity.externalId)
+        reporter.error("Permission request could not be sent", error)
+        conversation.error(identity.sessionID, "Permission request could not be sent")
+      })
   }
 
   async function handleTodoUpdated(event) {
@@ -107,9 +114,8 @@ export default async function BackeerPlugin({ client, directory }, options = {})
 
     const isComplete = todos.length > 0 &&
       todos.every((todo) => todo?.status === "completed")
-    const wasComplete = todoCompletionBySessionID.get(sessionID) === true
-    rememberBounded(todoCompletionBySessionID, sessionID, isComplete)
-    if (!isComplete || wasComplete) return
+    const attempt = todoCompletions.update(sessionID, isComplete)
+    if (!attempt) return
 
     void publishTodoCompletion(
       config,
@@ -119,10 +125,12 @@ export default async function BackeerPlugin({ client, directory }, options = {})
       client,
       directory,
       conversation,
-    ).catch((error) => {
-      reporter.error("Todo completion could not be sent", error)
-      conversation.error(sessionID, "Todo completion could not be sent")
-    })
+    ).then(() => todoCompletions.succeed(attempt))
+      .catch((error) => {
+        todoCompletions.fail(attempt)
+        reporter.error("Todo completion could not be sent", error)
+        conversation.error(sessionID, "Todo completion could not be sent")
+      })
   }
 
   async function handleQuestionAsked(event) {
@@ -131,8 +139,7 @@ export default async function BackeerPlugin({ client, directory }, options = {})
       reporter.error("Question event is missing correlation IDs")
       return
     }
-    if (publishedQuestions.has(identity.externalId)) return
-    rememberBounded(publishedQuestions, identity.externalId, true)
+    if (!questionPublications.begin(identity.externalId)) return
 
     void publishQuestion(
       config,
@@ -142,10 +149,12 @@ export default async function BackeerPlugin({ client, directory }, options = {})
       client,
       directory,
       conversation,
-    ).catch((error) => {
-      reporter.error("Question could not be sent", error)
-      conversation.error(identity.sessionID, "Question could not be sent")
-    })
+    ).then(() => questionPublications.succeed(identity.externalId))
+      .catch((error) => {
+        questionPublications.fail(identity.externalId)
+        reporter.error("Question could not be sent", error)
+        conversation.error(identity.sessionID, "Question could not be sent")
+      })
   }
 
   return {
@@ -191,8 +200,9 @@ export default async function BackeerPlugin({ client, directory }, options = {})
     dispose: async () => {
       await permissionController.dispose()
       lifecycleController.dispose()
-      todoCompletionBySessionID.clear()
-      publishedQuestions.clear()
+      permissionPublications.clear()
+      questionPublications.clear()
+      todoCompletions.clear()
       conversation.dispose()
     },
   }