fix: Improve plugin logging and add test/coverage CI (#11)

* Add debug logging mode for plugin

* Add log level support for plugin logging

* Add tests and CI checks

* Expand behavioral test coverage

* Add coverage reporting and Codecov upload

* Add repo guidance and Given/When/Then test comments

* Fix Codecov workflow guard

* Make Given/When/Then comments descriptive

* Fix session-context test typecheck

Author: lan17

.github/workflows/lint.yml

@@ -1,4 +1,4 @@
-name: Lint
+name: CI
 
 on:
   push:
@@ -15,7 +15,7 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  lint:
+  checks:
     runs-on: ubuntu-latest
     steps:
       - name: Check out repository
@@ -25,9 +25,35 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: "24"
+          cache: npm
 
       - name: Install dependencies
         run: npm ci
 
       - name: Run lint
         run: npm run lint
+
+      - name: Run typecheck
+        run: npm run typecheck
+
+      - name: Run coverage
+        run: npm run coverage
+
+      - name: Upload coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage
+
+      - name: Upload coverage to Codecov
+        if: ${{ env.CODECOV_TOKEN != '' }}
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+        uses: codecov/codecov-action@v5
+        with:
+          files: ./coverage/lcov.info
+          flags: unit
+          name: vitest-coverage
+          token: ${{ env.CODECOV_TOKEN }}
+          fail_ci_if_error: false
+          verbose: true

.gitignore

@@ -1 +1,2 @@
 node_modules/
+coverage/

AGENTS.md

@@ -0,0 +1,73 @@
+# AGENTS.md
+
+## Repo Scope
+
+This repository contains the Agent Control plugin for OpenClaw. It is a TypeScript ESM project that ships source files directly; there is no separate build step in normal development.
+
+## Local Verification
+
+Run the full local verification stack before finishing non-trivial changes:
+
+```bash
+npm run lint
+npm run typecheck
+npm test
+```
+
+When the change affects tests, coverage, or CI behavior, also run:
+
+```bash
+npm run coverage
+```
+
+Coverage output is written to `coverage/`, including `coverage/lcov.info` for Codecov-compatible uploads.
+
+## Testing Conventions
+
+- Prefer behavioral tests over implementation-detail tests.
+- Write test names as concise behavioral summaries.
+- Express Given/When/Then structure as code comments inside the test body.
+- Make each Given/When/Then comment descriptive. Do not use placeholder comments like `// Given`, `// When`, or `// Then` by themselves.
+- Use Vitest for unit and integration-style tests.
+- Assert externally visible outcomes first: return values, registered hooks, emitted logs, blocked tool calls, resolved context, and client calls.
+- Mock boundary dependencies such as `agent-control`, session/context helpers, and runtime-loading edges when needed, but keep the assertions focused on plugin behavior.
+- When adding a new branch in plugin logic, add or update tests in the corresponding `test/*.test.ts` file.
+
+Examples of the preferred naming style:
+
+- `it("defaults to warn", () => { ... })`
+- `it("blocks the tool call when fail-closed sync fails", async () => { ... })`
+
+Examples of the preferred comment style:
+
+- `// Given no logging configuration is provided`
+- `// When the effective log level is resolved`
+- `// Then warn mode is selected by default`
+
+## Project Conventions
+
+- Keep imports ESM-compatible and include the `.ts` suffix for local TypeScript imports, matching the current codebase style.
+- This repo uses `oxlint` for linting and `tsc --noEmit` for semantic typechecking. `npm run lint` is not a substitute for `npm run typecheck`.
+- Preserve the plugin's quiet default behavior. New logs should fit the existing `logLevel` model:
+  - `warn`: warnings, errors, and block events
+  - `info`: important lifecycle events
+  - `debug`: verbose diagnostics
+
+## When Changing Config or User-Facing Behavior
+
+Keep these files aligned when config shape or documented behavior changes:
+
+- `src/types.ts`
+- `openclaw.plugin.json`
+- `README.md`
+- relevant tests under `test/`
+
+If a change affects CI expectations or coverage behavior, also update:
+
+- `.github/workflows/lint.yml`
+- `package.json`
+- `vitest.config.ts`
+
+## CI Expectations
+
+The main GitHub Actions workflow is `.github/workflows/lint.yml`. Changes to scripts or coverage generation should keep local commands and CI steps in sync.

README.md

@@ -35,8 +35,14 @@ Then restart the gateway.
 
 ```bash
 npm install
+npm run lint
+npm run typecheck
+npm test
+npm run coverage
 ```
 
+Coverage reports are written to `coverage/`, including `coverage/lcov.info` for Codecov-compatible uploads. The GitHub Actions workflow will upload that report to Codecov automatically when a `CODECOV_TOKEN` secret is configured for the repository.
+
 3. Link it into your OpenClaw config from your OpenClaw checkout:
 
 ```bash
@@ -66,16 +72,29 @@ openclaw config set plugins.entries.agent-control-openclaw-plugin.config.timeout
 openclaw config set plugins.entries.agent-control-openclaw-plugin.config.failClosed false --strict-json
 
 # Optional settings
+openclaw config set plugins.entries.agent-control-openclaw-plugin.config.logLevel "info"
+openclaw config set plugins.entries.agent-control-openclaw-plugin.config.logLevel "debug"
 openclaw config set plugins.entries.agent-control-openclaw-plugin.config.agentId "00000000-0000-4000-8000-000000000000"
 openclaw config set plugins.entries.agent-control-openclaw-plugin.config.agentVersion "2026.3.3"
 openclaw config set plugins.entries.agent-control-openclaw-plugin.config.userAgent "agent-control-plugin/0.1"
 
 # Remove optional keys
 openclaw config unset plugins.entries.agent-control-openclaw-plugin.config.apiKey
+openclaw config unset plugins.entries.agent-control-openclaw-plugin.config.logLevel
+openclaw config unset plugins.entries.agent-control-openclaw-plugin.config.debug
 openclaw config unset plugins.entries.agent-control-openclaw-plugin.config.agentId
 openclaw config unset plugins.entries.agent-control-openclaw-plugin.config.agentVersion
 openclaw config unset plugins.entries.agent-control-openclaw-plugin.config.userAgent
 
 # Uninstall plugin link/install record from OpenClaw config
 openclaw plugins uninstall agent-control-openclaw-plugin --force
 ```
+
+By default the plugin stays quiet and only emits warnings, errors, and tool block events.
+
+Set `config.logLevel` to:
+
+- `info` for one-line lifecycle logs such as client init, warmup, and agent syncs
+- `debug` for verbose startup, sync, and evaluation diagnostics
+
+The older `config.debug` flag is still accepted as a deprecated alias for `logLevel=debug`.

openclaw.plugin.json

@@ -33,6 +33,13 @@
       },
       "failClosed": {
         "type": "boolean"
+      },
+      "logLevel": {
+        "type": "string",
+        "enum": ["warn", "info", "debug"]
+      },
+      "debug": {
+        "type": "boolean"
       }
     }
   },
@@ -56,6 +63,14 @@
     "failClosed": {
       "label": "Fail Closed",
       "help": "If true, block tool invocations when Agent Control is unavailable."
+    },
+    "logLevel": {
+      "label": "Log Level",
+      "help": "Controls plugin verbosity: warn logs only warnings, errors, and block events; info adds high-level lifecycle logs; debug adds verbose diagnostics."
+    },
+    "debug": {
+      "label": "Debug Logging",
+      "help": "Deprecated alias for logLevel=debug."
     }
   }
 }