@velanir/openclaw-participation-gate 0.1.0

package/README.md

@@ -0,0 +1,151 @@
+# Velanir OpenClaw Participation Gate
+
+OpenClaw plugin that decides whether a digital coworker should participate in a shared channel, group, room, or thread before the main agent runs.
+
+The plugin is designed for the `requireMention: false` use case: the coworker can observe channel traffic, but should only answer when the current turn is actually for that coworker.
+
+## Package
+
+- Package: `@velanir/openclaw-participation-gate`
+- OpenClaw plugin id: `velanir-participation-gate`
+- Runtime hooks: `before_dispatch`, `message_sent`
+- Default mode: `shadow`
+- Target OpenClaw plugin API: `>=2026.5.4`
+
+The platform monorepo owns the source package in `packages/openclaw-plugins/participation-gate`. Customer machines install the built package into their OpenClaw runtime.
+
+## Behavior
+
+Direct messages always pass through. The gate only evaluates group and channel messages.
+
+For group and channel messages, the plugin:
+
+1. Records recent shared-room user and coworker messages for fallback context.
+2. Loads participation context for the current coworker.
+3. Applies deterministic rules:
+   - respond when the message clearly addresses this coworker
+   - skip when the message clearly addresses another known coworker
+   - treat sentence-start requests such as `Albus I need you to...` as direct address without hardcoding coworker names
+4. Calls a lightweight classifier when deterministic rules do not decide the turn.
+5. Returns `{ handled: true }` only when the decision is skip and `mode` is `enforce`.
+
+Explicit mentions still bypass classifier enforcement, but the inbound turn is
+recorded before bypass so later unmentioned follow-ups have context. Successful
+`message_sent` events are also recorded as coworker replies, which lets the
+classifier recognize follow-ups after this coworker already answered.
+
+Any missing runtime dependency, missing context, invalid classifier output, classifier timeout, or classifier error fails open and lets the coworker respond. This is deliberate because false silence is worse than an occasional extra reply while the plugin is being rolled out.
+
+## Classifier Contract
+
+The classifier returns a scored participation decision:
+
+```json
+{ "participationScore": 0.83 }
+```
+
+The plugin participates when `participationScore >= classifier.threshold`. The default threshold is `0.7`.
+
+Legacy `{ "shouldRespond": true|false }` output is still accepted for
+compatibility, but the prompt asks for `participationScore` only.
+If the classifier output is malformed, the plugin retries once with a strict
+JSON repair prompt. If the score can still be recovered from truncated output,
+the recovered score is used for the skip/respond decision. If the retry is still
+malformed with no recoverable score, the plugin fails open with score `1.0` and
+logs `classifier_malformed` instead of treating it as a clean `classifier_true`.
+
+`classifier.maxOutputTokens` limits the classifier response only. It does not cap input context.
+
+Normal decision logs include the participation score, threshold, classifier
+prompt version, prompt hash, input hash, parse status, attempt count, output
+hash, and output length. Exact rendered prompt/input/raw classifier output and
+parse errors are logged only when `logging.classifierDebug` and
+`logging.includeContent` are both enabled.
+
+## Context Contract
+
+Production context should come from the platform:
+
+```http
+GET /v1/runtime/coworkers/{coworkerId}/participation-context
+Authorization: DPoP <scoped runtime token>
+DPoP: <proof for this GET request>
+Accept: application/json
+```
+
+Expected response:
+
+```json
+{
+  "data": {
+    "self": {
+      "id": "coworker_albus",
+      "names": ["Albus", "Albus Dumbledore"],
+      "roleSummary": "Executive assistant for Diagon leadership"
+    },
+    "coworkers": [
+      {
+        "id": "coworker_tanya",
+        "names": ["Tanya", "Tanya Dean", "Tanya Morales"],
+        "roleSummary": "Executive assistant"
+      }
+    ]
+  }
+}
+```
+
+The Platform endpoint must use the runtime identity protocol. The provider defaults to `platform.authMode: "runtime"`, requests `scope=participation-context:read` from `/v1/runtime/token`, and signs a DPoP proof for each context read.
+
+The endpoint must be derived from platform-owned coworker and organization data. Adding or removing a digital coworker should not require editing plugin configuration on customer machines.
+
+`names` should include display names, short names, and channel-specific aliases or mention tokens when the platform knows them. The deterministic direct-address rules depend on these aliases, and the classifier receives the same identity set.
+
+Static context exists only for tests and local development.
+
+## Security
+
+The platform provider intentionally does not fall back to a broad `OCT8_API_SECRET`.
+
+The production credential is a short-lived, DPoP-bound runtime token that can only read the current coworker's participation context. Static `platform.token` / `OCT8_PARTICIPATION_CONTEXT_TOKEN` is only read when `platform.authMode` is explicitly set to `static-token`; that mode remains prototype-only and must not be used to bypass runtime identity in live customer deployments.
+
+Runtime mode expects the same runtime identity environment used by `oct8-secrets-runtime-v2`: `OCT8_API_URL`, `OCT8_RUNTIME_IDENTITY_ID`, `OCT8_RUNTIME_STATE_DIR`, and optionally `OCT8_RUNTIME_TOKEN_ISSUER` / `OCT8_RUNTIME_KEY_ID`. It does not read `OCT8_API_SECRET`.
+
+## Example Config
+
+```json
+{
+  "mode": "shadow",
+  "classifier": {
+    "provider": "openai-codex",
+    "model": "gpt-5.5",
+    "timeoutMs": 5000,
+    "maxOutputTokens": 32,
+    "threshold": 0.7
+  },
+  "context": {
+    "source": "platform",
+    "maxMessages": 5,
+    "refreshMs": 300000
+  },
+  "platform": {
+    "authMode": "runtime",
+    "baseUrl": "https://api.velanir.ai",
+    "coworkerId": "coworker_albus"
+  },
+  "logging": {
+    "decisions": true,
+    "includeContent": false,
+    "classifierDebug": false
+  }
+}
+```
+
+Use `shadow` first to validate decisions in logs. Move to `enforce` only after the classifier and context source are behaving as expected. Platform-rendered configs should choose the coworker's configured OpenClaw model/provider unless an explicit classifier override is present.
+
+## Development
+
+```sh
+pnpm --filter=@velanir/openclaw-participation-gate check-types
+pnpm --filter=@velanir/openclaw-participation-gate test
+pnpm --filter=@velanir/openclaw-participation-gate build
+```

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import * as openclaw_plugin_sdk_plugin_entry from 'openclaw/plugin-sdk/plugin-entry';
+
+declare const PLUGIN_ID = "velanir-participation-gate";
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: openclaw_plugin_sdk_plugin_entry.OpenClawPluginConfigSchema;
+    register: NonNullable<openclaw_plugin_sdk_plugin_entry.OpenClawPluginDefinition["register"]>;
+} & Pick<openclaw_plugin_sdk_plugin_entry.OpenClawPluginDefinition, "kind" | "reload" | "nodeHostCommands" | "securityAuditCollectors">;
+
+export { PLUGIN_ID, _default as default };