backeer-opencode 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to `backeer-opencode` are documented here.
 
+## 0.1.5 - 2026-09-01
+
+- Check the NPM registry for a newer Backeer plugin version once per day.
+- Notify the OpenCode agent once per session when an update is available.
+- Add `/backeer update-check` for an explicit registry check.
+- Add `/backeer update` to delegate an exact-version installation and
+  verification workflow to the OpenCode agent.
+- Require the agent workflow to preserve the token and avoid `@latest` cache
+  ambiguity.
+
+## 0.1.4 - 2026-09-01
+
+- Add `/backeer` and `/backeer status` for an in-session integration report.
+- Add secure, immediate token rotation with `/backeer token-file PATH`.
+- Keep raw tokens out of slash-command arguments, session messages, and logs.
+- Keep the management command available when notifications are disabled by a
+  missing token.
+
 ## 0.1.3 - 2026-09-01
 
 - Split configuration, logging, HTTP, SSE, event publishing, and permission

package/README.md

@@ -149,6 +149,45 @@ connection errors are suppressed for 30 seconds. Normal `info` output omits HTTP
 status codes and internal errors; set `BACKEER_LOG_LEVEL=debug` when technical
 details are needed. Set it to `error` for failures only or `silent` for no output.
 
+## OpenCode command
+
+The plugin registers a `/backeer` command inside OpenCode:
+
+```text
+/backeer
+/backeer status
+/backeer update-check
+/backeer update
+/backeer token
+/backeer token-file /absolute/path/to/a/protected-token-file
+```
+
+The status report shows the plugin version, gateway reachability, token source,
+notification switches, command-stream state, pending permissions, and log level.
+It never displays the token. Gateway reachability does not validate the source
+credential.
+
+`/backeer token` displays safe rotation instructions. Never paste a raw token
+into slash-command arguments because OpenCode may retain command text in session
+history. To rotate from inside OpenCode, first place the new token in an absolute
+file readable only by its owner (`chmod 600`), then use `token-file`. The plugin
+atomically copies it to the configured token location, applies mode `0600`, and
+activates it immediately without restarting OpenCode. The source file is not
+removed.
+
+The plugin checks the NPM registry at most once every 24 hours. When a newer
+version exists, it adds one synthetic update notice to each OpenCode session so
+the agent can inform the user. The notice never authorizes installation by
+itself.
+
+`/backeer update-check` performs an explicit check. `/backeer update` is the
+user authorization point: it gives the OpenCode agent an exact-version install
+command, requires verification of both the global version pin and package
+cache, and forbids reading or changing the Backeer token. The agent does not
+terminate the active OpenCode process; restart OpenCode after a successful
+update. Exact versions are used instead of `@latest` to avoid stale OpenCode
+package caches.
+
 ## Events and decisions
 
 The plugin publishes:

package/dist/backeer-permission.js

@@ -83,11 +83,12 @@ function defaultConfigDirectory() {
 }
 function loadToken(tokenFile) {
   const environmentToken = process.env.BACKEER_INGEST_TOKEN?.trim();
-  if (environmentToken) return environmentToken;
+  if (environmentToken) return { token: environmentToken, source: "environment" };
   try {
-    return readFileSync(tokenFile, "utf8").trim();
+    const token = readFileSync(tokenFile, "utf8").trim();
+    return { token, source: token ? "file" : "missing" };
   } catch {
-    return "";
+    return { token: "", source: "missing" };
   }
 }
 function loadConfig(options = {}) {
@@ -98,11 +99,13 @@ function loadConfig(options = {}) {
     throw new Error("Backeer origin must use HTTPS");
   }
   const tokenFile = options.tokenFile ?? process.env.BACKEER_TOKEN_FILE ?? join(defaultConfigDirectory(), "secrets", "backeer-ingest-token");
+  const loadedToken = loadToken(tokenFile);
   return {
     origin,
     eventsEndpoint: new URL("/v1/events", origin),
     commandStreamEndpoint: new URL("/v1/commands/stream", origin),
-    token: loadToken(tokenFile),
+    token: loadedToken.token,
+    tokenSource: loadedToken.source,
     tokenFile,
     permissions: enabled(
       options.permissions ?? process.env.BACKEER_NOTIFY_PERMISSIONS
@@ -134,16 +137,16 @@ function isAbortError(error) {
   return error instanceof Error && error.name === "AbortError";
 }
 function sleep(milliseconds, signal) {
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     if (signal?.aborted) {
-      resolve();
+      resolve2();
       return;
     }
     const timeout = setTimeout(done, milliseconds);
     function done() {
       clearTimeout(timeout);
       signal?.removeEventListener("abort", done);
-      resolve();
+      resolve2();
     }
     signal?.addEventListener("abort", done, { once: true });
   });
@@ -344,6 +347,343 @@ async function publishTodoCompletion(config, reporter, request, eventID, client,
   reporter.success("Todo completion sent", `HTTP ${result.status}`);
 }
 
+// src/management.js
+import {
+  chmodSync,
+  mkdirSync,
+  readFileSync as readFileSync2,
+  renameSync,
+  statSync,
+  writeFileSync
+} from "node:fs";
+import { dirname, resolve } from "node:path";
+
+// src/updates.js
+var PLUGIN_VERSION = "0.1.5";
+var PACKAGE_NAME = "backeer-opencode";
+var NPM_REGISTRY_URL = "https://registry.npmjs.org";
+var CHECK_TIMEOUT_MS = 3e3;
+var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+function parseVersion(value) {
+  const match = String(value).trim().match(
+    /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/
+  );
+  if (!match) return;
+  return {
+    parts: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4]
+  };
+}
+function isVersionNewer(latestValue, currentValue) {
+  const latest = parseVersion(latestValue);
+  const current = parseVersion(currentValue);
+  if (!latest || !current) return false;
+  for (let index = 0; index < 3; index++) {
+    if (latest.parts[index] > current.parts[index]) return true;
+    if (latest.parts[index] < current.parts[index]) return false;
+  }
+  if (!latest.prerelease && current.prerelease) return true;
+  if (latest.prerelease && !current.prerelease) return false;
+  return Boolean(
+    latest.prerelease && current.prerelease && latest.prerelease !== current.prerelease
+  );
+}
+function createUpdateChecker({
+  fetchImplementation = globalThis.fetch,
+  now = () => Date.now()
+} = {}) {
+  let checkedAt = 0;
+  let cachedResult;
+  let pendingCheck;
+  async function fetchLatest() {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS);
+    try {
+      const response = await fetchImplementation(
+        `${NPM_REGISTRY_URL}/${PACKAGE_NAME}/latest`,
+        { signal: controller.signal }
+      );
+      if (!response.ok) return { state: "unavailable", currentVersion: PLUGIN_VERSION };
+      const data = await response.json();
+      const latestVersion = typeof data?.version === "string" ? data.version.trim() : "";
+      if (!parseVersion(latestVersion)) {
+        return { state: "unavailable", currentVersion: PLUGIN_VERSION };
+      }
+      if (!isVersionNewer(latestVersion, PLUGIN_VERSION)) {
+        return {
+          state: "current",
+          currentVersion: PLUGIN_VERSION,
+          latestVersion
+        };
+      }
+      return {
+        state: "available",
+        currentVersion: PLUGIN_VERSION,
+        latestVersion,
+        updateCommand: `opencode plugin ${PACKAGE_NAME}@${latestVersion} -g --force`
+      };
+    } catch {
+      return { state: "unavailable", currentVersion: PLUGIN_VERSION };
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  return {
+    async check({ force = false } = {}) {
+      if (!force && checkedAt && now() - checkedAt < CHECK_INTERVAL_MS) {
+        return cachedResult;
+      }
+      if (pendingCheck) return pendingCheck;
+      pendingCheck = fetchLatest().then((result) => {
+        cachedResult = result;
+        checkedAt = now();
+        return result;
+      }).finally(() => {
+        pendingCheck = void 0;
+      });
+      return pendingCheck;
+    }
+  };
+}
+function formatAgentUpdateInstruction(info) {
+  return [
+    "[BACKEER UPDATE REQUESTED]",
+    `The user explicitly requested the Backeer OpenCode plugin update from v${info.currentVersion} to v${info.latestVersion}.`,
+    `Run exactly: ${info.updateCommand}`,
+    "Then verify that the global OpenCode config is pinned to the exact new version and that the matching package exists in the OpenCode cache.",
+    "Do not read, print, replace, or otherwise expose the Backeer token.",
+    "Do not use @latest and do not claim success until both installation and verification pass.",
+    "Do not terminate the active OpenCode process; tell the user to restart OpenCode after success."
+  ].join("\n");
+}
+function createUpdateNoticeHook(updateChecker) {
+  const notifiedSessions = /* @__PURE__ */ new Set();
+  return async (input, output) => {
+    if (notifiedSessions.has(input.sessionID)) return;
+    notifiedSessions.add(input.sessionID);
+    const info = await updateChecker.check();
+    if (info.state !== "available") return;
+    output.parts.push({
+      id: `prt_backeer-update-${Date.now()}`,
+      sessionID: input.sessionID,
+      messageID: output.message.id,
+      type: "text",
+      synthetic: true,
+      text: [
+        "[BACKEER UPDATE AVAILABLE]",
+        `Backeer OpenCode plugin v${info.latestVersion} is available; current version is v${info.currentVersion}.`,
+        "Inform the user that an update is available and suggest `/backeer update`.",
+        "Do not install it solely because of this notice."
+      ].join("\n")
+    });
+  };
+}
+
+// src/management.js
+var COMMAND_DESCRIPTION = "Show Backeer status, update it, or manage its token: /backeer [status|update-check|update|token|token-file PATH]";
+function tokenFileState(path) {
+  try {
+    const stats = statSync(path);
+    const mode = (stats.mode & 511).toString(8).padStart(3, "0");
+    return stats.isFile() ? `present (mode ${mode})` : "not a regular file";
+  } catch {
+    return "missing";
+  }
+}
+function cleanPathArgument(value) {
+  const path = value.trim();
+  if (path.length >= 2 && (path.startsWith('"') && path.endsWith('"') || path.startsWith("'") && path.endsWith("'"))) {
+    return path.slice(1, -1);
+  }
+  return path;
+}
+function writeTokenAtomically(path, token) {
+  mkdirSync(dirname(path), { recursive: true, mode: 448 });
+  const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temporaryPath, `${token}
+`, { encoding: "utf8", mode: 384 });
+  chmodSync(temporaryPath, 384);
+  renameSync(temporaryPath, path);
+}
+function rotateTokenFromFile(config, sourcePathValue) {
+  if (!sourcePathValue.trim()) throw new Error("A token file path is required");
+  const sourcePath = resolve(cleanPathArgument(sourcePathValue));
+  const sourceStats = statSync(sourcePath);
+  if (!sourceStats.isFile()) throw new Error("The token source is not a regular file");
+  if ((sourceStats.mode & 63) !== 0) {
+    throw new Error("The token source must not be readable by group or other users");
+  }
+  const token = readFileSync2(sourcePath, "utf8").trim();
+  if (!token || /\s/.test(token)) {
+    throw new Error("The token source must contain exactly one non-empty token");
+  }
+  const targetPath = resolve(config.tokenFile);
+  if (sourcePath !== targetPath) writeTokenAtomically(targetPath, token);
+  else chmodSync(targetPath, 384);
+  config.token = token;
+  config.tokenSource = "file";
+  return targetPath;
+}
+async function probeGateway(config) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 3e3);
+  try {
+    const response = await fetch(config.origin, {
+      method: "HEAD",
+      redirect: "manual",
+      signal: controller.signal
+    });
+    return `reachable (HTTP ${response.status}; authentication not tested)`;
+  } catch {
+    return "unreachable";
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function updateStatus(info) {
+  if (info.state === "available") {
+    return `v${info.latestVersion} available \u2014 use /backeer update`;
+  }
+  if (info.state === "current") return `current (v${info.currentVersion})`;
+  return "check unavailable";
+}
+async function buildStatus(config, permissionController, updateChecker) {
+  const [gateway, update] = await Promise.all([
+    probeGateway(config),
+    updateChecker.check()
+  ]);
+  const permissionStatus = permissionController.status();
+  return [
+    "## Backeer status",
+    "",
+    `- Plugin version: ${PLUGIN_VERSION}`,
+    `- Update: ${updateStatus(update)}`,
+    `- Gateway: ${config.origin.origin} \u2014 ${gateway}`,
+    `- Token: ${config.token ? `configured via ${config.tokenSource}` : "missing"}`,
+    `- Token file: ${config.tokenFile} \u2014 ${tokenFileState(config.tokenFile)}`,
+    `- Permission notifications: ${config.permissions ? "enabled" : "disabled"}`,
+    `- Question notifications: ${config.questions ? "enabled" : "disabled"}`,
+    `- Todo notifications: ${config.todos ? "enabled" : "disabled"}`,
+    `- Command stream: ${permissionStatus.stream}`,
+    `- Pending permissions: ${permissionStatus.pending}`,
+    `- Log level: ${config.logLevel}`,
+    "",
+    "The token value is never displayed."
+  ].join("\n");
+}
+function helpMessage() {
+  return [
+    "## Backeer commands",
+    "",
+    "- `/backeer` or `/backeer status` \u2014 show integration status",
+    "- `/backeer update-check` \u2014 check NPM for a newer version",
+    "- `/backeer update` \u2014 ask the OpenCode agent to install and verify it",
+    "- `/backeer token` \u2014 show secure token-change instructions",
+    "- `/backeer token-file /absolute/protected/path` \u2014 import and activate a token",
+    "",
+    "Never place a token directly in a slash command. Slash-command arguments may be stored in session history."
+  ].join("\n");
+}
+function tokenInstructions() {
+  return [
+    "## Change the Backeer token securely",
+    "",
+    "Do not paste the token into OpenCode or `/backeer` arguments.",
+    "",
+    "Use either:",
+    "",
+    "1. Hidden terminal input: `npx backeer-opencode@latest configure`",
+    "2. A protected file: `chmod 600 /path/to/token && /backeer token-file /path/to/token`",
+    "",
+    "`token-file` activates the new token immediately; no OpenCode restart is required."
+  ].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 }]
+    }
+  });
+}
+function registerBackeerCommand(opencodeConfig) {
+  opencodeConfig.command ??= {};
+  opencodeConfig.command.backeer = {
+    template: "",
+    description: COMMAND_DESCRIPTION
+  };
+}
+function createBackeerCommandHandler({
+  client,
+  config,
+  permissionController,
+  reporter,
+  updateChecker
+}) {
+  return async (input, output) => {
+    if (input.command !== "backeer") return;
+    output.parts.length = 0;
+    const argumentsValue = (input.arguments ?? "").trim();
+    const separator = argumentsValue.indexOf(" ");
+    const subcommand = (separator === -1 ? argumentsValue : argumentsValue.slice(0, separator)).toLowerCase();
+    const subcommandArguments = separator === -1 ? "" : argumentsValue.slice(separator + 1).trim();
+    let message;
+    try {
+      if (!subcommand || subcommand === "status") {
+        message = await buildStatus(config, permissionController, updateChecker);
+      } else if (subcommand === "update-check") {
+        const update = await updateChecker.check({ force: true });
+        message = [
+          "## Backeer update check",
+          "",
+          update.state === "available" ? `Version ${update.latestVersion} is available; current version is ${update.currentVersion}. Use \`/backeer update\` to let the OpenCode agent install and verify it.` : update.state === "current" ? `Backeer is current at version ${update.currentVersion}.` : "The NPM registry could not be reached. No update was attempted."
+        ].join("\n");
+      } else if (subcommand === "update") {
+        const update = await updateChecker.check({ force: true });
+        if (update.state === "available") {
+          output.parts.push({
+            type: "text",
+            text: formatAgentUpdateInstruction(update)
+          });
+          return;
+        }
+        message = update.state === "current" ? `## Backeer update
+
+Backeer is already current at version ${update.currentVersion}.` : "## Backeer update\n\nThe NPM registry could not be reached. No update was attempted.";
+      } else if (subcommand === "token") {
+        message = tokenInstructions();
+      } else if (subcommand === "token-file") {
+        const targetPath = rotateTokenFromFile(config, subcommandArguments);
+        permissionController.refreshCredentials();
+        reporter.success("Access token updated");
+        message = [
+          "## Backeer token updated",
+          "",
+          `- Protected token file: ${targetPath}`,
+          "- File mode: 600",
+          "- The new token is active immediately."
+        ].join("\n");
+      } else {
+        message = helpMessage();
+      }
+    } catch (error) {
+      reporter.error("Access token could not be updated", error);
+      message = [
+        "## Backeer command failed",
+        "",
+        error instanceof Error ? error.message : String(error),
+        "",
+        "Use `/backeer token` for secure token-change instructions."
+      ].join("\n");
+    }
+    await sendCommandMessage(client, input.sessionID, message);
+  };
+}
+
 // src/sse.js
 function parseSseFrame(frame) {
   const data = [];
@@ -605,6 +945,16 @@ function createPermissionController({
       removePendingByRequestID(requestID);
       stopCommandStreamIfIdle();
     },
+    refreshCredentials() {
+      commandStream?.controller.abort();
+      if (!commandStream) ensureCommandStream();
+    },
+    status() {
+      return {
+        pending: pendingByExternalID.size,
+        stream: commandStream ? "active" : "idle"
+      };
+    },
     async dispose() {
       disposed = true;
       commandStream?.controller.abort();
@@ -632,13 +982,6 @@ async function BackeerPlugin({ client, directory }, options = {}) {
     return {};
   }
   const reporter = createConsoleReporter(config.logLevel);
-  if (!config.token) {
-    reporter.error(
-      "Plugin disabled \u2014 run: npx backeer-opencode@latest configure",
-      `Token not found at ${config.tokenFile}`
-    );
-    return {};
-  }
   const permissionController = createPermissionController({
     config,
     reporter,
@@ -647,6 +990,21 @@ async function BackeerPlugin({ client, directory }, options = {}) {
   });
   const todoCompletionBySessionID = /* @__PURE__ */ new Map();
   const publishedQuestions = /* @__PURE__ */ new Map();
+  const updateChecker = createUpdateChecker();
+  const handleBackeerCommand = createBackeerCommandHandler({
+    client,
+    config,
+    permissionController,
+    reporter,
+    updateChecker
+  });
+  const handleUpdateNotice = createUpdateNoticeHook(updateChecker);
+  if (!config.token) {
+    reporter.error(
+      "Notifications disabled \u2014 use /backeer token",
+      `Token not found at ${config.tokenFile}`
+    );
+  }
   async function handlePermissionAsked(event) {
     const identity = permissionIdentity(event.properties);
     if (!identity) {
@@ -699,7 +1057,13 @@ async function BackeerPlugin({ client, directory }, options = {}) {
     ).catch((error) => reporter.error("Question could not be sent", error));
   }
   return {
+    config: async (opencodeConfig) => {
+      registerBackeerCommand(opencodeConfig);
+    },
+    "command.execute.before": handleBackeerCommand,
+    "chat.message": handleUpdateNotice,
     event: async ({ event }) => {
+      if (!config.token) return;
       if (config.permissions && event.type === "permission.asked") {
         await handlePermissionAsked(event);
         return;

package/package.json

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

package/src/config.js

@@ -14,12 +14,13 @@ function defaultConfigDirectory() {
 
 function loadToken(tokenFile) {
   const environmentToken = process.env.BACKEER_INGEST_TOKEN?.trim()
-  if (environmentToken) return environmentToken
+  if (environmentToken) return { token: environmentToken, source: "environment" }
 
   try {
-    return readFileSync(tokenFile, "utf8").trim()
+    const token = readFileSync(tokenFile, "utf8").trim()
+    return { token, source: token ? "file" : "missing" }
   } catch {
-    return ""
+    return { token: "", source: "missing" }
   }
 }
 
@@ -36,11 +37,13 @@ export function loadConfig(options = {}) {
     process.env.BACKEER_TOKEN_FILE ??
     join(defaultConfigDirectory(), "secrets", "backeer-ingest-token")
 
+  const loadedToken = loadToken(tokenFile)
   return {
     origin,
     eventsEndpoint: new URL("/v1/events", origin),
     commandStreamEndpoint: new URL("/v1/commands/stream", origin),
-    token: loadToken(tokenFile),
+    token: loadedToken.token,
+    tokenSource: loadedToken.source,
     tokenFile,
     permissions: enabled(
       options.permissions ?? process.env.BACKEER_NOTIFY_PERMISSIONS,

package/src/management.js

@@ -0,0 +1,248 @@
+import {
+  chmodSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "node:fs"
+import { dirname, resolve } from "node:path"
+
+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]"
+
+function tokenFileState(path) {
+  try {
+    const stats = statSync(path)
+    const mode = (stats.mode & 0o777).toString(8).padStart(3, "0")
+    return stats.isFile() ? `present (mode ${mode})` : "not a regular file"
+  } catch {
+    return "missing"
+  }
+}
+
+function cleanPathArgument(value) {
+  const path = value.trim()
+  if (
+    path.length >= 2 &&
+    ((path.startsWith('"') && path.endsWith('"')) ||
+      (path.startsWith("'") && path.endsWith("'")))
+  ) {
+    return path.slice(1, -1)
+  }
+  return path
+}
+
+function writeTokenAtomically(path, token) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
+  const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`
+  writeFileSync(temporaryPath, `${token}\n`, { encoding: "utf8", mode: 0o600 })
+  chmodSync(temporaryPath, 0o600)
+  renameSync(temporaryPath, path)
+}
+
+export function rotateTokenFromFile(config, sourcePathValue) {
+  if (!sourcePathValue.trim()) throw new Error("A token file path is required")
+  const sourcePath = resolve(cleanPathArgument(sourcePathValue))
+
+  const sourceStats = statSync(sourcePath)
+  if (!sourceStats.isFile()) throw new Error("The token source is not a regular file")
+  if ((sourceStats.mode & 0o077) !== 0) {
+    throw new Error("The token source must not be readable by group or other users")
+  }
+
+  const token = readFileSync(sourcePath, "utf8").trim()
+  if (!token || /\s/.test(token)) {
+    throw new Error("The token source must contain exactly one non-empty token")
+  }
+
+  const targetPath = resolve(config.tokenFile)
+  if (sourcePath !== targetPath) writeTokenAtomically(targetPath, token)
+  else chmodSync(targetPath, 0o600)
+  config.token = token
+  config.tokenSource = "file"
+  return targetPath
+}
+
+async function probeGateway(config) {
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), 3000)
+  try {
+    const response = await fetch(config.origin, {
+      method: "HEAD",
+      redirect: "manual",
+      signal: controller.signal,
+    })
+    return `reachable (HTTP ${response.status}; authentication not tested)`
+  } catch {
+    return "unreachable"
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+function updateStatus(info) {
+  if (info.state === "available") {
+    return `v${info.latestVersion} available — use /backeer update`
+  }
+  if (info.state === "current") return `current (v${info.currentVersion})`
+  return "check unavailable"
+}
+
+async function buildStatus(config, permissionController, updateChecker) {
+  const [gateway, update] = await Promise.all([
+    probeGateway(config),
+    updateChecker.check(),
+  ])
+  const permissionStatus = permissionController.status()
+  return [
+    "## Backeer status",
+    "",
+    `- Plugin version: ${PLUGIN_VERSION}`,
+    `- Update: ${updateStatus(update)}`,
+    `- Gateway: ${config.origin.origin} — ${gateway}`,
+    `- Token: ${config.token ? `configured via ${config.tokenSource}` : "missing"}`,
+    `- Token file: ${config.tokenFile} — ${tokenFileState(config.tokenFile)}`,
+    `- Permission notifications: ${config.permissions ? "enabled" : "disabled"}`,
+    `- Question notifications: ${config.questions ? "enabled" : "disabled"}`,
+    `- Todo notifications: ${config.todos ? "enabled" : "disabled"}`,
+    `- Command stream: ${permissionStatus.stream}`,
+    `- Pending permissions: ${permissionStatus.pending}`,
+    `- Log level: ${config.logLevel}`,
+    "",
+    "The token value is never displayed.",
+  ].join("\n")
+}
+
+function helpMessage() {
+  return [
+    "## Backeer commands",
+    "",
+    "- `/backeer` or `/backeer status` — show integration status",
+    "- `/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",
+    "- `/backeer token-file /absolute/protected/path` — import and activate a token",
+    "",
+    "Never place a token directly in a slash command. Slash-command arguments may be stored in session history.",
+  ].join("\n")
+}
+
+function tokenInstructions() {
+  return [
+    "## Change the Backeer token securely",
+    "",
+    "Do not paste the token into OpenCode or `/backeer` arguments.",
+    "",
+    "Use either:",
+    "",
+    "1. Hidden terminal input: `npx backeer-opencode@latest configure`",
+    "2. A protected file: `chmod 600 /path/to/token && /backeer token-file /path/to/token`",
+    "",
+    "`token-file` activates the new token immediately; no OpenCode restart is required.",
+  ].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 = {
+    template: "",
+    description: COMMAND_DESCRIPTION,
+  }
+}
+
+export function createBackeerCommandHandler({
+  client,
+  config,
+  permissionController,
+  reporter,
+  updateChecker,
+}) {
+  return async (input, output) => {
+    if (input.command !== "backeer") return
+    output.parts.length = 0
+
+    const argumentsValue = (input.arguments ?? "").trim()
+    const separator = argumentsValue.indexOf(" ")
+    const subcommand = (
+      separator === -1 ? argumentsValue : argumentsValue.slice(0, separator)
+    ).toLowerCase()
+    const subcommandArguments = separator === -1
+      ? ""
+      : argumentsValue.slice(separator + 1).trim()
+
+    let message
+    try {
+      if (!subcommand || subcommand === "status") {
+        message = await buildStatus(config, permissionController, updateChecker)
+      } else if (subcommand === "update-check") {
+        const update = await updateChecker.check({ force: true })
+        message = [
+          "## Backeer update check",
+          "",
+          update.state === "available"
+            ? `Version ${update.latestVersion} is available; current version is ${update.currentVersion}. Use \`/backeer update\` to let the OpenCode agent install and verify it.`
+            : update.state === "current"
+              ? `Backeer is current at version ${update.currentVersion}.`
+              : "The NPM registry could not be reached. No update was attempted.",
+        ].join("\n")
+      } else if (subcommand === "update") {
+        const update = await updateChecker.check({ force: true })
+        if (update.state === "available") {
+          output.parts.push({
+            type: "text",
+            text: formatAgentUpdateInstruction(update),
+          })
+          return
+        }
+        message = update.state === "current"
+          ? `## Backeer update\n\nBackeer is already current at version ${update.currentVersion}.`
+          : "## Backeer update\n\nThe NPM registry could not be reached. No update was attempted."
+      } else if (subcommand === "token") {
+        message = tokenInstructions()
+      } else if (subcommand === "token-file") {
+        const targetPath = rotateTokenFromFile(config, subcommandArguments)
+        permissionController.refreshCredentials()
+        reporter.success("Access token updated")
+        message = [
+          "## Backeer token updated",
+          "",
+          `- Protected token file: ${targetPath}`,
+          "- File mode: 600",
+          "- The new token is active immediately.",
+        ].join("\n")
+      } else {
+        message = helpMessage()
+      }
+    } catch (error) {
+      reporter.error("Access token could not be updated", error)
+      message = [
+        "## Backeer command failed",
+        "",
+        error instanceof Error ? error.message : String(error),
+        "",
+        "Use `/backeer token` for secure token-change instructions.",
+      ].join("\n")
+    }
+
+    await sendCommandMessage(client, input.sessionID, message)
+  }
+}

package/src/permission-controller.js

@@ -169,6 +169,18 @@ export function createPermissionController({
       stopCommandStreamIfIdle()
     },
 
+    refreshCredentials() {
+      commandStream?.controller.abort()
+      if (!commandStream) ensureCommandStream()
+    },
+
+    status() {
+      return {
+        pending: pendingByExternalID.size,
+        stream: commandStream ? "active" : "idle",
+      }
+    },
+
     async dispose() {
       disposed = true
       commandStream?.controller.abort()

package/src/plugin.js

@@ -6,8 +6,16 @@ import {
   publishTodoCompletion,
   questionIdentity,
 } from "./event-publishers.js"
+import {
+  createBackeerCommandHandler,
+  registerBackeerCommand,
+} from "./management.js"
 import { createPermissionController } from "./permission-controller.js"
 import { createConsoleReporter } from "./reporter.js"
+import {
+  createUpdateChecker,
+  createUpdateNoticeHook,
+} from "./updates.js"
 import { rememberBounded } from "./utilities.js"
 
 /**
@@ -31,14 +39,6 @@ export default async function BackeerPlugin({ client, directory }, options = {})
 
   const reporter = createConsoleReporter(config.logLevel)
 
-  if (!config.token) {
-    reporter.error(
-      "Plugin disabled — run: npx backeer-opencode@latest configure",
-      `Token not found at ${config.tokenFile}`,
-    )
-    return {}
-  }
-
   const permissionController = createPermissionController({
     config,
     reporter,
@@ -47,6 +47,22 @@ export default async function BackeerPlugin({ client, directory }, options = {})
   })
   const todoCompletionBySessionID = new Map()
   const publishedQuestions = new Map()
+  const updateChecker = createUpdateChecker()
+  const handleBackeerCommand = createBackeerCommandHandler({
+    client,
+    config,
+    permissionController,
+    reporter,
+    updateChecker,
+  })
+  const handleUpdateNotice = createUpdateNoticeHook(updateChecker)
+
+  if (!config.token) {
+    reporter.error(
+      "Notifications disabled — use /backeer token",
+      `Token not found at ${config.tokenFile}`,
+    )
+  }
 
   async function handlePermissionAsked(event) {
     const identity = permissionIdentity(event.properties)
@@ -108,7 +124,17 @@ export default async function BackeerPlugin({ client, directory }, options = {})
   }
 
   return {
+    config: async (opencodeConfig) => {
+      registerBackeerCommand(opencodeConfig)
+    },
+
+    "command.execute.before": handleBackeerCommand,
+
+    "chat.message": handleUpdateNotice,
+
     event: async ({ event }) => {
+      if (!config.token) return
+
       if (config.permissions && event.type === "permission.asked") {
         await handlePermissionAsked(event)
         return

package/src/updates.js

@@ -0,0 +1,136 @@
+export const PLUGIN_VERSION = "0.1.5"
+
+const PACKAGE_NAME = "backeer-opencode"
+const NPM_REGISTRY_URL = "https://registry.npmjs.org"
+const CHECK_TIMEOUT_MS = 3000
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000
+
+export function parseVersion(value) {
+  const match = String(value).trim().match(
+    /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/,
+  )
+  if (!match) return
+  return {
+    parts: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4],
+  }
+}
+
+export function isVersionNewer(latestValue, currentValue) {
+  const latest = parseVersion(latestValue)
+  const current = parseVersion(currentValue)
+  if (!latest || !current) return false
+
+  for (let index = 0; index < 3; index++) {
+    if (latest.parts[index] > current.parts[index]) return true
+    if (latest.parts[index] < current.parts[index]) return false
+  }
+  if (!latest.prerelease && current.prerelease) return true
+  if (latest.prerelease && !current.prerelease) return false
+  return Boolean(
+    latest.prerelease &&
+    current.prerelease &&
+    latest.prerelease !== current.prerelease,
+  )
+}
+
+export function createUpdateChecker({
+  fetchImplementation = globalThis.fetch,
+  now = () => Date.now(),
+} = {}) {
+  let checkedAt = 0
+  let cachedResult
+  let pendingCheck
+
+  async function fetchLatest() {
+    const controller = new AbortController()
+    const timeout = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS)
+    try {
+      const response = await fetchImplementation(
+        `${NPM_REGISTRY_URL}/${PACKAGE_NAME}/latest`,
+        { signal: controller.signal },
+      )
+      if (!response.ok) return { state: "unavailable", currentVersion: PLUGIN_VERSION }
+      const data = await response.json()
+      const latestVersion = typeof data?.version === "string"
+        ? data.version.trim()
+        : ""
+      if (!parseVersion(latestVersion)) {
+        return { state: "unavailable", currentVersion: PLUGIN_VERSION }
+      }
+      if (!isVersionNewer(latestVersion, PLUGIN_VERSION)) {
+        return {
+          state: "current",
+          currentVersion: PLUGIN_VERSION,
+          latestVersion,
+        }
+      }
+      return {
+        state: "available",
+        currentVersion: PLUGIN_VERSION,
+        latestVersion,
+        updateCommand:
+          `opencode plugin ${PACKAGE_NAME}@${latestVersion} -g --force`,
+      }
+    } catch {
+      return { state: "unavailable", currentVersion: PLUGIN_VERSION }
+    } finally {
+      clearTimeout(timeout)
+    }
+  }
+
+  return {
+    async check({ force = false } = {}) {
+      if (!force && checkedAt && now() - checkedAt < CHECK_INTERVAL_MS) {
+        return cachedResult
+      }
+      if (pendingCheck) return pendingCheck
+
+      pendingCheck = fetchLatest()
+        .then((result) => {
+          cachedResult = result
+          checkedAt = now()
+          return result
+        })
+        .finally(() => { pendingCheck = undefined })
+      return pendingCheck
+    },
+  }
+}
+
+export function formatAgentUpdateInstruction(info) {
+  return [
+    "[BACKEER UPDATE REQUESTED]",
+    `The user explicitly requested the Backeer OpenCode plugin update from v${info.currentVersion} to v${info.latestVersion}.`,
+    `Run exactly: ${info.updateCommand}`,
+    "Then verify that the global OpenCode config is pinned to the exact new version and that the matching package exists in the OpenCode cache.",
+    "Do not read, print, replace, or otherwise expose the Backeer token.",
+    "Do not use @latest and do not claim success until both installation and verification pass.",
+    "Do not terminate the active OpenCode process; tell the user to restart OpenCode after success.",
+  ].join("\n")
+}
+
+export function createUpdateNoticeHook(updateChecker) {
+  const notifiedSessions = new Set()
+
+  return async (input, output) => {
+    if (notifiedSessions.has(input.sessionID)) return
+    notifiedSessions.add(input.sessionID)
+
+    const info = await updateChecker.check()
+    if (info.state !== "available") return
+    output.parts.push({
+      id: `prt_backeer-update-${Date.now()}`,
+      sessionID: input.sessionID,
+      messageID: output.message.id,
+      type: "text",
+      synthetic: true,
+      text: [
+        "[BACKEER UPDATE AVAILABLE]",
+        `Backeer OpenCode plugin v${info.latestVersion} is available; current version is v${info.currentVersion}.`,
+        "Inform the user that an update is available and suggest `/backeer update`.",
+        "Do not install it solely because of this notice.",
+      ].join("\n"),
+    })
+  }
+}