backeer-opencode 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backeer-opencode",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Backeer lifecycle notifications and remote permission decisions for OpenCode",
   "type": "module",
   "main": "./src/index.js",

package/src/config.js

@@ -85,6 +85,7 @@ export function loadConfig(options = {}) {
   return {
     origin,
     eventsEndpoint: new URL("/v1/events", origin),
+    sourceHealthEndpoint: new URL("/v1/source/health", origin),
     commandStreamEndpoint: new URL("/v1/commands/stream", origin),
     token: loadedToken.token,
     tokenSource: loadedToken.source,

package/src/diagnostics.js

@@ -0,0 +1,148 @@
+import { randomUUID } from "node:crypto"
+import { statSync } from "node:fs"
+
+import { HttpError, postJsonWithRetry } from "./http.js"
+import { PLUGIN_VERSION } from "./updates.js"
+import { limit } from "./utilities.js"
+
+const PASS = "✓"
+const FAIL = "×"
+const INFO = "•"
+
+function tokenFileCheck(config) {
+  if (config.tokenSource === "environment") {
+    return { ok: true, text: "Token loaded from the environment; token file not required" }
+  }
+  try {
+    const stats = statSync(config.tokenFile)
+    const mode = stats.mode & 0o777
+    if (!stats.isFile()) return { ok: false, text: "Token path is not a regular file" }
+    if ((mode & 0o077) !== 0) {
+      return {
+        ok: false,
+        text: `Token file mode ${(mode).toString(8).padStart(3, "0")} is too permissive; expected 600`,
+      }
+    }
+    return {
+      ok: true,
+      text: `Token file is protected (mode ${mode.toString(8).padStart(3, "0")})`,
+    }
+  } catch {
+    return { ok: false, text: "Token file is missing or unreadable" }
+  }
+}
+
+async function probeSource(config, fetchImplementation = globalThis.fetch) {
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), 5000)
+  try {
+    const response = await fetchImplementation(config.sourceHealthEndpoint, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${config.token}` },
+      signal: controller.signal,
+    })
+    const responseBody = limit(await response.text(), 2000)
+    if (!response.ok) {
+      throw new HttpError(
+        `Gateway source check failed with status ${response.status}`,
+        response.status,
+        responseBody,
+      )
+    }
+    try {
+      return JSON.parse(responseBody)
+    } catch {
+      throw new Error("Gateway source check returned malformed JSON")
+    }
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+export async function buildDoctorReport(
+  config,
+  { fetchImplementation = globalThis.fetch } = {},
+) {
+  const checks = []
+  checks.push({ ok: true, text: `Plugin version ${PLUGIN_VERSION}` })
+  checks.push({
+    ok: config.origin.protocol === "https:",
+    text: `Gateway uses ${config.origin.protocol === "https:" ? "HTTPS" : "an insecure protocol"}: ${config.origin.origin}`,
+  })
+  checks.push({
+    ok: Boolean(config.token),
+    text: config.token
+      ? `Source token loaded from ${config.tokenSource}`
+      : "Source token is missing",
+  })
+  checks.push(tokenFileCheck(config))
+
+  let source
+  if (config.token) {
+    try {
+      const result = await probeSource(config, fetchImplementation)
+      source = result?.source
+      checks.push({
+        ok: result?.ok === true && typeof source?.id === "string",
+        text: source?.id
+          ? `Source authentication accepted: ${source.name || source.id} (${source.id})`
+          : "Gateway did not return a source identity",
+      })
+      checks.push({
+        ok: result?.capabilities?.events === true &&
+          result?.capabilities?.commands === true,
+        text: result?.capabilities?.events === true &&
+          result?.capabilities?.commands === true
+          ? "Event ingest and command stream are available"
+          : "Event ingest or command stream is unavailable",
+      })
+      checks.push({
+        ok: result?.capabilities?.apns === true,
+        text: result?.capabilities?.apns === true
+          ? "Gateway APNs delivery is enabled"
+          : "Gateway APNs delivery is disabled",
+      })
+    } catch (error) {
+      const detail = error instanceof HttpError && error.status === 401
+        ? "Source authentication rejected (HTTP 401)"
+        : error?.name === "AbortError"
+          ? "Gateway source check timed out"
+          : `Gateway source check failed: ${limit(error?.message || error, 300)}`
+      checks.push({ ok: false, text: detail })
+    }
+  }
+
+  const healthy = checks.every((check) => check.ok)
+  return [
+    "## Backeer doctor",
+    "",
+    ...checks.map((check) => `${check.ok ? PASS : FAIL} ${check.text}`),
+    "",
+    healthy
+      ? `${PASS} Result: healthy. Use \`/backeer test\` to verify phone delivery.`
+      : `${FAIL} Result: issues found. Resolve failed checks and run \`/backeer doctor\` again.`,
+    "",
+    `${INFO} No event was created and the token value was not displayed.`,
+  ].join("\n")
+}
+
+export async function publishTestNotification(config, reporter) {
+  if (!config.token) throw new Error("Backeer source token is missing")
+  const testID = randomUUID()
+  const result = await postJsonWithRetry(config, config.eventsEndpoint, {
+    type: "application",
+    severity: "info",
+    title: "Backeer test notification",
+    body: "OpenCode integration is connected and push delivery is working.",
+    payload: [
+      { key: "Plugin version", value: PLUGIN_VERSION },
+      { key: "Test ID", value: testID },
+    ],
+    externalId: `opencode:test:${testID}`,
+    timestamp: new Date().toISOString(),
+    notify: true,
+    direction: "in",
+  })
+  reporter.success("Test notification sent", `HTTP ${result.status}`)
+  return testID
+}

package/src/event-publishers.js

@@ -21,6 +21,7 @@ export async function publishPermission(
   request,
   directory,
   identity,
+  conversation,
 ) {
   const permissionType = request.permission ?? request.action ?? "unknown"
   const resources = Array.isArray(request.patterns)
@@ -53,6 +54,7 @@ export async function publishPermission(
     direction: "in",
   })
   reporter.success("Permission request sent", `HTTP ${result.status}`)
+  conversation?.success(identity.sessionID, "Permission request sent")
 }
 
 export function questionIdentity(request) {
@@ -104,6 +106,7 @@ export async function publishQuestion(
   identity,
   client,
   directory,
+  conversation,
 ) {
   const questions = Array.isArray(request.questions) ? request.questions : []
   if (questions.length === 0) return
@@ -153,6 +156,7 @@ export async function publishQuestion(
     direction: "in",
   })
   reporter.success("Question sent", `HTTP ${result.status}`)
+  conversation?.success(identity.sessionID, "Question sent")
 }
 
 export async function publishTodoCompletion(
@@ -162,6 +166,7 @@ export async function publishTodoCompletion(
   eventID,
   client,
   directory,
+  conversation,
 ) {
   const todos = request.todos
   const sessionTitle = await resolveSessionTitle(
@@ -211,4 +216,5 @@ export async function publishTodoCompletion(
     direction: "in",
   })
   reporter.success("Todo completion sent", `HTTP ${result.status}`)
+  conversation?.success(request.sessionID, "Todo completion sent")
 }

package/src/lifecycle-controller.js

@@ -20,6 +20,7 @@ export function createLifecycleController({
   reporter,
   client,
   directory,
+  conversation,
   now = () => Date.now(),
   publishers = {},
 }) {
@@ -47,8 +48,11 @@ export function createLifecycleController({
     return state
   }
 
-  function dispatch(label, operation) {
-    void Promise.resolve(operation).catch((error) => reporter.error(label, error))
+  function dispatch(label, operation, sessionID) {
+    void Promise.resolve(operation).catch((error) => {
+      reporter.error(label, error)
+      conversation?.error(sessionID, label)
+    })
   }
 
   function beginCycle(state) {
@@ -83,7 +87,9 @@ export function createLifecycleController({
         sessionID,
         messageID: limit(assistant.id, 200),
         durationMs,
+        conversation,
       }),
+      sessionID,
     )
   }
 
@@ -135,7 +141,9 @@ export function createLifecycleController({
         correlation: limit(correlation, 200),
         attempt: status.attempt,
         next: status.next,
+        conversation,
       }),
+      sessionID,
     )
   }
 
@@ -157,7 +165,9 @@ export function createLifecycleController({
         sessionID,
         correlation: errorCorrelation(event, state),
         error: event.properties?.error,
+        conversation,
       }),
+      sessionID,
     )
   }
 

package/src/lifecycle-publishers.js

@@ -53,7 +53,7 @@ async function resolveSessionTitle(client, directory, sessionID, reporter) {
   }
 }
 
-async function publish(config, reporter, event, feedback) {
+async function publish(config, reporter, conversation, sessionID, event, feedback) {
   const result = await postJsonWithRetry(config, config.eventsEndpoint, {
     type: "application",
     timestamp: new Date().toISOString(),
@@ -62,6 +62,7 @@ async function publish(config, reporter, event, feedback) {
     ...event,
   })
   reporter.success(feedback, `HTTP ${result.status}`)
+  conversation?.success(sessionID, feedback)
 }
 
 function secondsLabel(durationMs) {
@@ -80,6 +81,7 @@ export async function publishSessionCompleted({
   sessionID,
   messageID,
   durationMs,
+  conversation,
 }) {
   const sessionTitle = await resolveSessionTitle(
     client,
@@ -89,7 +91,7 @@ export async function publishSessionCompleted({
   )
   const duration = secondsLabel(durationMs)
   const location = sessionTitle ? ` “${sessionTitle}”` : ""
-  await publish(config, reporter, {
+  await publish(config, reporter, conversation, sessionID, {
     severity: "info",
     title: "OpenCode task completed",
     body: `OpenCode finished${location} in ${duration}.`,
@@ -111,6 +113,7 @@ export async function publishSessionRetry({
   correlation,
   attempt,
   next,
+  conversation,
 }) {
   const sessionTitle = await resolveSessionTitle(
     client,
@@ -119,7 +122,7 @@ export async function publishSessionRetry({
     reporter,
   )
   const retryAt = Number.isFinite(next) ? new Date(next).toISOString() : ""
-  await publish(config, reporter, {
+  await publish(config, reporter, conversation, sessionID, {
     severity: "warning",
     title: "OpenCode is retrying",
     body: `OpenCode reached retry attempt ${attempt}. The operation is still running.`,
@@ -140,6 +143,7 @@ export async function publishSessionError({
   sessionID,
   correlation,
   error,
+  conversation,
 }) {
   const sessionTitle = await resolveSessionTitle(
     client,
@@ -152,7 +156,7 @@ export async function publishSessionError({
   const body = details.message
     ? `OpenCode failed${location}: ${details.message}`
     : `OpenCode failed${location}.`
-  await publish(config, reporter, {
+  await publish(config, reporter, conversation, sessionID, {
     // Backeer/iOS currently support info, warning and critical severities.
     severity: "critical",
     title: "OpenCode task failed",
@@ -170,7 +174,7 @@ export async function publishSessionError({
 
 export async function publishOpenCodeUpdate({ config, reporter, version }) {
   const safeVersion = limit(version, 100)
-  await publish(config, reporter, {
+  await publish(config, reporter, undefined, undefined, {
     severity: "info",
     title: "OpenCode update available",
     body: `OpenCode ${safeVersion} is available.`,

package/src/management.js

@@ -8,13 +8,15 @@ import {
 } from "node:fs"
 import { dirname, resolve } from "node:path"
 
+import { buildDoctorReport, publishTestNotification } from "./diagnostics.js"
+import { sendSessionMessage } from "./session-messages.js"
 import {
   formatAgentUpdateInstruction,
   PLUGIN_VERSION,
 } from "./updates.js"
 
 const COMMAND_DESCRIPTION =
-  "Show Backeer status, update it, or manage its token: /backeer [status|update-check|update|token|token-file PATH]"
+  "Check, test, update, or manage Backeer: /backeer [status|doctor|test|update-check|update|token|token-file PATH]"
 
 function tokenFileState(path) {
   try {
@@ -129,6 +131,8 @@ function helpMessage() {
     "## Backeer commands",
     "",
     "- `/backeer` or `/backeer status` — show integration status",
+    "- `/backeer doctor` — diagnose config, credentials, gateway, and APNs without creating an event",
+    "- `/backeer test` — send a real test notification to the Backeer application",
     "- `/backeer update-check` — check NPM for a newer version",
     "- `/backeer update` — ask the OpenCode agent to install and verify it",
     "- `/backeer token` — show secure token-change instructions",
@@ -153,19 +157,6 @@ function tokenInstructions() {
   ].join("\n")
 }
 
-async function sendCommandMessage(client, sessionID, text) {
-  if (typeof client?.session?.prompt !== "function") {
-    throw new Error("OpenCode session messaging is unavailable")
-  }
-  await client.session.prompt({
-    path: { id: sessionID },
-    body: {
-      noReply: true,
-      parts: [{ type: "text", text, ignored: true }],
-    },
-  })
-}
-
 export function registerBackeerCommand(opencodeConfig) {
   opencodeConfig.command ??= {}
   opencodeConfig.command.backeer = {
@@ -198,6 +189,17 @@ export function createBackeerCommandHandler({
     try {
       if (!subcommand || subcommand === "status") {
         message = await buildStatus(config, permissionController, updateChecker)
+      } else if (subcommand === "doctor") {
+        message = await buildDoctorReport(config)
+      } else if (subcommand === "test") {
+        const testID = await publishTestNotification(config, reporter)
+        message = [
+          "## Backeer test notification",
+          "",
+          "✓ The gateway accepted the test event.",
+          `- Test ID: ${testID}`,
+          "- Check the Backeer application for the notification.",
+        ].join("\n")
       } else if (subcommand === "update-check") {
         const update = await updateChecker.check({ force: true })
         message = [
@@ -238,7 +240,7 @@ export function createBackeerCommandHandler({
         message = helpMessage()
       }
     } catch (error) {
-      reporter.error("Access token could not be updated", error)
+      reporter.error("Backeer command failed", error)
       message = [
         "## Backeer command failed",
         "",
@@ -248,6 +250,6 @@ export function createBackeerCommandHandler({
       ].join("\n")
     }
 
-    await sendCommandMessage(client, input.sessionID, message)
+    await sendSessionMessage(client, input.sessionID, message)
   }
 }

package/src/permission-controller.js

@@ -35,6 +35,7 @@ export function createPermissionController({
   reporter,
   client,
   directory,
+  conversation,
 }) {
   const pendingByExternalID = new Map()
   const externalIDByRequestID = new Map()
@@ -104,6 +105,7 @@ export function createPermissionController({
       }
       if (stale) removePendingByRequestID(pending.requestID)
       reporter.error("Decision could not be applied", error)
+      conversation?.error(pending.sessionID, "Decision could not be applied")
     } finally {
       processingCommands.delete(command.id)
     }
@@ -120,12 +122,19 @@ export function createPermissionController({
       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")
     }
 
     await acknowledgeCommand(config, command.id, acknowledgement).catch((error) => {

package/src/plugin.js

@@ -12,7 +12,8 @@ import {
 } from "./management.js"
 import { createLifecycleController } from "./lifecycle-controller.js"
 import { createPermissionController } from "./permission-controller.js"
-import { createConsoleReporter } from "./reporter.js"
+import { createOpenCodeReporter } from "./reporter.js"
+import { createConversationFeedback } from "./session-messages.js"
 import {
   createUpdateChecker,
   createUpdateNoticeHook,
@@ -28,7 +29,8 @@ import { rememberBounded } from "./utilities.js"
  * protected file so it cannot accidentally be committed in opencode.json.
  */
 export default async function BackeerPlugin({ client, directory }, options = {}) {
-  const bootstrapReporter = createConsoleReporter(
+  const bootstrapReporter = createOpenCodeReporter(
+    client,
     options.logLevel ?? process.env.BACKEER_LOG_LEVEL,
   )
   let config
@@ -39,19 +41,22 @@ export default async function BackeerPlugin({ client, directory }, options = {})
     return {}
   }
 
-  const reporter = createConsoleReporter(config.logLevel)
+  const reporter = createOpenCodeReporter(client, config.logLevel)
+  const conversation = createConversationFeedback({ client, reporter })
 
   const permissionController = createPermissionController({
     config,
     reporter,
     client,
     directory,
+    conversation,
   })
   const lifecycleController = createLifecycleController({
     config,
     reporter,
     client,
     directory,
+    conversation,
   })
   const todoCompletionBySessionID = new Map()
   const publishedQuestions = new Map()
@@ -86,7 +91,11 @@ export default async function BackeerPlugin({ client, directory }, options = {})
       event.properties,
       directory,
       identity,
-    ).catch((error) => reporter.error("Permission request could not be sent", error))
+      conversation,
+    ).catch((error) => {
+      reporter.error("Permission request could not be sent", error)
+      conversation.error(identity.sessionID, "Permission request could not be sent")
+    })
   }
 
   async function handleTodoUpdated(event) {
@@ -109,7 +118,11 @@ export default async function BackeerPlugin({ client, directory }, options = {})
       event.id,
       client,
       directory,
-    ).catch((error) => reporter.error("Todo completion could not be sent", error))
+      conversation,
+    ).catch((error) => {
+      reporter.error("Todo completion could not be sent", error)
+      conversation.error(sessionID, "Todo completion could not be sent")
+    })
   }
 
   async function handleQuestionAsked(event) {
@@ -128,7 +141,11 @@ export default async function BackeerPlugin({ client, directory }, options = {})
       identity,
       client,
       directory,
-    ).catch((error) => reporter.error("Question could not be sent", error))
+      conversation,
+    ).catch((error) => {
+      reporter.error("Question could not be sent", error)
+      conversation.error(identity.sessionID, "Question could not be sent")
+    })
   }
 
   return {
@@ -143,6 +160,7 @@ export default async function BackeerPlugin({ client, directory }, options = {})
     event: async ({ event }) => {
       if (!config.token) return
 
+      conversation.handle(event)
       lifecycleController.handle(event)
 
       if (config.permissions && event.type === "permission.asked") {
@@ -175,6 +193,7 @@ export default async function BackeerPlugin({ client, directory }, options = {})
       lifecycleController.dispose()
       todoCompletionBySessionID.clear()
       publishedQuestions.clear()
+      conversation.dispose()
     },
   }
 }

package/src/reporter.js

@@ -58,3 +58,53 @@ export function createConsoleReporter(levelValue) {
     debug: (message, detail) => emit("debug", "debug", message, detail),
   }
 }
+
+export function createOpenCodeReporter(client, levelValue) {
+  const level = normalizeLogLevel(levelValue)
+  const recentlyEmitted = new Map()
+  const method = client?.app?.log
+
+  function emit(requiredLevel, kind, message, detail, deduplicate = false) {
+    if (LOG_RANK[level] < LOG_RANK[requiredLevel] || typeof method !== "function") return
+
+    const key = `${kind}:${message}`
+    const now = Date.now()
+    if (deduplicate) {
+      const previous = recentlyEmitted.get(key)
+      if (previous && now - previous < LOG_DEDUPLICATION_MS) return
+      rememberRecent(recentlyEmitted, key, now)
+    }
+
+    const body = {
+      service: "backeer-opencode",
+      level: kind === "warning" ? "warn" : kind === "applied" || kind === "success"
+        ? "info"
+        : kind,
+      message: limit(message, 500),
+    }
+    if (level === "debug" && detail) {
+      body.extra = { detail: limit(detail?.message ?? detail, 500) }
+    }
+
+    // Logging during plugin initialization can deadlock older OpenCode builds.
+    // Defer it and never fall back to stdout, because stdout corrupts the TUI prompt.
+    setTimeout(() => {
+      void Promise.resolve(method.call(client.app, { body })).catch(() => {})
+    }, 0)
+  }
+
+  return {
+    info: (message, detail) => emit("info", "info", message, detail),
+    success: (message, detail) => emit("info", "success", message, detail),
+    applied: (message, detail) => emit("info", "applied", message, detail),
+    warning: (message, detail) => emit("error", "warning", message, detail, true),
+    error: (message, detail) => emit("error", "error", message, detail, true),
+    debug: (message, detail) => emit("debug", "debug", message, detail),
+  }
+}
+
+function rememberRecent(map, key, value) {
+  map.delete(key)
+  map.set(key, value)
+  while (map.size > 100) map.delete(map.keys().next().value)
+}