@aryaminus/controlkeel-opencode 0.2.17 → 0.2.19

package/.opencode/skills/agent-integration/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: agent-integration
+description: "Attach ControlKeel to agents, verify MCP connectivity, confirm native skills availability, and choose the right distribution target for each client."
+license: Apache-2.0
+compatibility:
+  - codex
+  - claude-standalone
+  - claude-plugin
+  - copilot-plugin
+  - github-repo
+  - open-standard
+disable-model-invocation: true
+metadata:
+  author: controlkeel
+  version: "2.0"
+  category: integration
+---
+
+# Agent Integration Skill
+
+Use this skill when the task is attaching or distributing ControlKeel across agents.
+
+## Workflow
+
+1. Identify whether the target is native-skill capable, plugin-capable, or MCP-only.
+2. Prefer native install where supported, with CK MCP as the transport for governance tools.
+3. Export plugin bundles when the user wants a shareable package.
+4. For MCP-only tools, generate the instruction bundle and installation guidance.
+5. For Conductor, prefer the Claude Code install path because Conductor documents support for `.mcp.json`, `CLAUDE.md`, and `.claude/commands`.
+
+## Cursor (Rules, Skills, Agents, Hooks, Plugins)
+
+Cursor’s **Settings → Rules, Skills, Subagents** (and related **Commands**, **Hooks**, **Plugins**) align to repo files ControlKeel already generates on `controlkeel attach cursor`:
+
+| Cursor concept | CK attach output | Notes |
+| --- | --- | --- |
+| **Rules** | `.cursor/rules/controlkeel.mdc` | Always-on governance instructions for the agent. |
+| **Skills** | `.cursor/skills/*` plus `.agents/skills/*` | Native Cursor skills tree plus open-standard AgentSkills for import tools. |
+| **Commands** | `.cursor/commands/*.md` | Slash-style review / plan / annotate / last flows. |
+| **Agents / Subagents** | `.cursor/agents/*.md`, `.cursor/background-agents/*.md` | Governor-style prompts and background workflow guidance; hooks include `subagentStart`. |
+| **Hooks** | `.cursor/hooks.json`, `.cursor/hooks/*.sh` | Shell / write / MCP / session / stop gates calling `controlkeel validate` when available. |
+| **MCP** | `.cursor/mcp.json` | Stdio MCP; use `${workspaceFolder}` for command paths and `CK_PROJECT_ROOT`. |
+| **Plugins** | `.cursor-plugin/` | Distributable bundle (`plugin.json`, mirrored assets, `hooks/hooks.json`, `mcpServers`) for **Plugins → Install** / marketplace-style flows. |
+
+**Install path:** `controlkeel attach cursor` in the governed repo root, then enable the ControlKeel MCP server in Cursor and (if desired) install the generated `.cursor-plugin` from the repo or a release export.
+
+## Additional resources
+
+- [Target matrix](references/target-matrix.md)

package/.opencode/skills/agent-integration/agents/openai.yaml

@@ -0,0 +1,11 @@
+interface:
+  display_name: "Agent Integration"
+  short_description: "Attach and distribute ControlKeel across native and MCP-only agent clients."
+  brand_color: "#0891b2"
+policy:
+  allow_implicit_invocation: false
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "controlkeel"
+      description: "ControlKeel MCP server"

package/.opencode/skills/agent-integration/references/target-matrix.md

@@ -0,0 +1,21 @@
+# Target Matrix
+
+## Native-first
+
+- Codex: `.agents/skills`, `.codex/agents`
+- Claude Code: `.claude/skills`, `.claude/agents`, plugins
+- Copilot / VS Code: `.github/skills`, `.github/agents`, plugins
+- Cursor: `.cursor/skills`, `.cursor/agents`, `.cursor/rules`, `.cursor/hooks.json`, `.cursor/mcp.json`, `.cursor-plugin/`
+- Conductor compatibility: use Claude Code repo-local surfaces (`.mcp.json`, `CLAUDE.md`, `.claude/commands`)
+
+## MCP-only fallback
+
+- Windsurf
+- Kiro
+- Amp
+- OpenCode
+- Gemini CLI
+- Continue
+- Aider
+
+All MCP-only tools should still receive CK instruction snippets so the model knows how and when to call CK tools.

package/.opencode/skills/benchmark-operator/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: benchmark-operator
+description: "Run, inspect, import, and export ControlKeel benchmark suites and multi-subject matrices. Use this when comparing governed and external agents or validating policy changes."
+license: Apache-2.0
+compatibility:
+  - codex
+  - claude-standalone
+  - claude-plugin
+  - copilot-plugin
+  - github-repo
+  - open-standard
+disable-model-invocation: true
+metadata:
+  author: controlkeel
+  version: "2.0"
+  category: benchmark
+---
+
+# Benchmark Operator Skill
+
+Use this skill when the task is benchmark orchestration instead of normal governed delivery work.
+
+## Workflow
+
+1. Select the suite and subjects.
+2. Run the suite or import manual outputs.
+3. Review catch rate, block rate, expected-rule hit rate, latency, and overhead.
+4. Export the run if you need external analysis.
+
+## Additional resources
+
+- [Benchmark operator playbook](references/benchmark-playbook.md)
+

package/.opencode/skills/benchmark-operator/agents/openai.yaml

@@ -0,0 +1,12 @@
+interface:
+  display_name: "Benchmark Operator"
+  short_description: "Operate CK benchmark suites and multi-agent matrices."
+  brand_color: "#065f46"
+policy:
+  allow_implicit_invocation: false
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "controlkeel"
+      description: "ControlKeel MCP server"
+

package/.opencode/skills/benchmark-operator/references/benchmark-playbook.md

@@ -0,0 +1,6 @@
+# Benchmark Operator Playbook
+
+- Public suites are for comparable external reporting and normal operator use.
+- Held-out suites should stay internal and only feed policy training and promotion gates.
+- Benchmark runs must not be confused with governed sessions or ship metrics.
+

package/.opencode/skills/cloudflare-agent/SKILL.md

@@ -0,0 +1,366 @@
+---
+name: cloudflare-agent
+description: "Enable ControlKeel governance for Cloudflare Agents with policy gates, budget enforcement, PII detection, and secure execution."
+license: Apache-2.0
+compatibility:
+  - cloudflare-workers-runtime
+  - open-standard
+disable-model-invocation: true
+metadata:
+  author: controlkeel
+  version: "1.0"
+  category: integration
+---
+
+# Cloudflare Agent Governance
+
+## Overview
+
+This skill enables ControlKeel to govern Cloudflare Agents by providing policy gates, budget enforcement, audit logging, and secure execution capabilities.
+
+## When to Use
+
+Use this skill when:
+- Building Cloudflare Agents that need governance guardrails
+- Enforcing budget/spend limits on Workers AI or external providers
+- Auditing agent actions for compliance
+- Running shell commands in sandboxed environments within CF Agents
+- Integrating PII detection and security scanning
+
+## Prerequisites
+
+- Cloudflare Workers project with Agents SDK installed
+- ControlKeel MCP connected to the agent
+- For shell tools: ExecutionSandbox adapter (local/docker/e2b)
+
+## Integration Pattern
+
+### 1. Connect CK to Cloudflare Agent via MCP
+
+The agent exposes governance tools via MCP:
+
+```typescript
+import { McpAgent } from "agents/mcp";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+export class GovernedAgent extends McpAgent {
+  server = new McpServer({
+    name: "controlkeel-governance",
+    version: "1.0.0"
+  });
+
+  async init() {
+    // Register CK governance tools
+    this.server.tool(
+      "ck_validate",
+      "Validate an action against governance policies",
+      { prompt: z.string(), context: z.record(z.string(), z.any()).optional() },
+      async ({ prompt, context }) => {
+        // Call CK governance endpoint
+        return await this.callCKGovernance(prompt, context);
+      }
+    );
+
+    this.server.tool(
+      "ck_budget_check",
+      "Check remaining budget for AI spend",
+      { scope: z.enum(["task", "session", "daily"]).optional() },
+      async ({ scope }) => {
+        // Query CK budget state
+        return await this.callCKBudget(scope || "task");
+      }
+    );
+  }
+
+  async callCKGovernance(prompt: string, context?: Record<string, any>) {
+    const response = await this.env.CK_GOVERNANCE.fetch("/validate", {
+      method: "POST",
+      body: JSON.stringify({ prompt, context })
+    });
+    return response.json();
+  }
+}
+```
+
+### 2. Policy Gate Pattern
+
+Validate before execution:
+
+```typescript
+export class GovernedAgent extends Agent {
+  @callable()
+  async executeWithGovernance(command: string, args: string[]) {
+    // Pre-execution policy check
+    const validation = await this.validateWithCK({
+      action: "execute_command",
+      payload: { command, args }
+    });
+
+    if (validation.decision === "denied") {
+      return { error: "Policy violation", reason: validation.reason };
+    }
+
+    // Execute if approved
+    const result = await this.executeCommand(command, args);
+
+    // Post-execution audit
+    await this.auditWithCK({
+      action: "command_executed",
+      payload: { command, args, result },
+      validation_id: validation.id
+    });
+
+    return result;
+  }
+}
+```
+
+### 3. Budget Enforcement
+
+```typescript
+export class BudgetedAgent extends Agent {
+  @callable()
+  async callAIWithBudget(model: string, messages: any[]) {
+    // Check budget before AI call
+    const budget = await this.ckBudgetCheck("task");
+    
+    if (!budget.has_remaining) {
+      return { error: "Budget exhausted", remaining: 0 };
+    }
+
+    // Make AI call
+    const response = await this.callAI(model, messages);
+
+    // Deduct from budget
+    await this.ckBudgetDeduct({
+      amount: response.usage_tokens,
+      scope: "task"
+    });
+
+    return response;
+  }
+}
+```
+
+### 4. Shell Execution (via CK ExecutionSandbox)
+
+For agents that need shell access:
+
+```typescript
+export class ShellEnabledAgent extends Agent {
+  @callable()
+  async shell(command: string, cwd?: string) {
+    // Validate shell command
+    const validation = await this.validateWithCK({
+      action: "shell_execution",
+      payload: { command, cwd }
+    });
+
+    if (validation.decision === "denied") {
+      throw new Error(`Shell denied: ${validation.reason}`);
+    }
+
+    // Execute via CK sandbox (local/docker/e2b)
+    const result = await this.env.CK_SANDBOX.fetch("/execute", {
+      method: "POST",
+      body: JSON.stringify({
+        command,
+        cwd: cwd || this.state.cwd || "/workspace",
+        sandbox: "local" // or docker, e2b
+      })
+    });
+
+    return result.json();
+  }
+}
+```
+
+### 5. File System via R2
+
+```typescript
+export class FileEnabledAgent extends Agent {
+  @callable()
+  async readFile(path: string) {
+    const object = await this.env.AGENT_BUCKET.get(path);
+    if (!object) throw new Error(`File not found: ${path}`);
+    return await object.text();
+  }
+
+  @callable()
+  async writeFile(path: string, content: string) {
+    await this.env.AGENT_BUCKET.put(path, content);
+    return { success: true, path };
+  }
+
+  @callable()
+  async listFiles(prefix: string) {
+    const objects = await this.env.AGENT_BUCKET.list({ prefix });
+    return objects.objects.map(o => o.key);
+  }
+}
+```
+
+### 6. SQLite via D1
+
+```typescript
+export class DBEnabledAgent extends Agent {
+  @callable()
+  async query(sql: string, params?: any[]) {
+    const stmt = await this.env.DB.prepare(sql);
+    return params ? stmt.bind(...params).all() : stmt.all();
+  }
+
+  @callable()
+  async initSchema() {
+    await this.env.DB.exec(`
+      CREATE TABLE IF NOT EXISTS agent_state (
+        key TEXT PRIMARY KEY,
+        value TEXT,
+        updated_at INTEGER
+      );
+    `);
+  }
+}
+```
+
+## Tools Reference
+
+### MCP Tools (serve to agents)
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `ck_validate` | Validate action against policies | `prompt`, `context` |
+| `ck_budget_check` | Check remaining budget | `scope` |
+| `ck_budget_deduct` | Deduct from budget | `amount`, `scope` |
+| `ck_finding` | Log a finding | `severity`, `message`, `payload` |
+| `ck_context` | Get governance context | - |
+| `ck_delegate` | Delegate to sub-agent | `agent`, `task` |
+
+### CK to Agent Tools
+
+| Tool | Description |
+|------|-------------|
+| `ck_shell` | Execute shell command (sandboxed) |
+| `ck_read` | Read file from agent workspace |
+| `ck_write` | Write file to agent workspace |
+| `ck_ai` | Call AI with budget tracking |
+
+## Environment Variables
+
+```bash
+# CK Governance endpoint (Durable Object or external)
+CK_GOVERNANCE=do://agent-governance
+
+# CK Sandbox endpoint
+CK_SANDBOX=do://agent-sandbox
+
+# Agent bucket (R2)
+AGENT_BUCKET=agent-workspace
+
+# Agent database (D1)
+DB=agent-db
+```
+
+## Example: Complete Governed Agent
+
+```typescript
+import { Agent, callable } from "agents";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+type Env = {
+  CK_GOVERNANCE: DurableObjectNamespace;
+  AGENT_BUCKET: R2Bucket;
+  DB: D1Database;
+  AI: Ai;
+};
+
+export class GovernedCFAgent extends Agent<Env, { cwd: string }> {
+  initialState = { cwd: "/workspace" };
+
+  async onStart() {
+    await this.initDB();
+  }
+
+  async initDB() {
+    await this.env.DB.exec(`
+      CREATE TABLE IF NOT EXISTS logs (
+        id INTEGER PRIMARY KEY,
+        action TEXT,
+        payload TEXT,
+        timestamp INTEGER
+      );
+    `);
+  }
+
+  @callable()
+  async executeCommand(cmd: string, args: string[]) {
+    // 1. Validate
+    const validation = await this.validateAction("execute", { cmd, args });
+    if (validation.denied) {
+      await this.log("validation_denied", { cmd, reason: validation.reason });
+      return { error: validation.reason };
+    }
+
+    // 2. Execute
+    const result = await this.runCommand(cmd, args);
+
+    // 3. Audit
+    await this.log("executed", { cmd, args, exitCode: result.exitCode });
+
+    return result;
+  }
+
+  @callable()
+  async readFile(path: string) {
+    const fullPath = `${this.state.cwd}/${path}`;
+    const obj = await this.env.AGENT_BUCKET.get(fullPath);
+    return obj?.text() || null;
+  }
+
+  @callable()
+  async writeFile(path: string, content: string) {
+    const fullPath = `${this.state.cwd}/${path}`;
+    await this.env.AGENT_BUCKET.put(fullPath, content);
+    await this.log("file_written", { path: fullPath });
+    return { success: true };
+  }
+
+  private async validateAction(action: string, payload: any) {
+    const stub = this.env.CK_GOVERNANCE.get(this.env.CK_GOVERNANCE.idFromName("default"));
+    return await stub.validate({ action, payload, context: this.state });
+  }
+
+  private async log(action: string, payload: any) {
+    await this.env.DB.prepare(
+      "INSERT INTO logs (action, payload, timestamp) VALUES (?, ?, ?)"
+    ).bind(action, JSON.stringify(payload), Date.now()).run();
+  }
+
+  private async runCommand(cmd: string, args: string[]): Promise<{ output: string; exitCode: number }> {
+    // Execute via CK sandbox or direct
+    const fullCommand = [cmd, ...args].join(" ");
+    return { output: `Executed: ${fullCommand}`, exitCode: 0 };
+  }
+}
+```
+
+## Security Considerations
+
+1. **Shell commands** - Always validate via CK policy gates before execution
+2. **File access** - Restrict to workspace directory, validate paths
+3. **AI budget** - Set per-task and daily limits
+4. **Audit logging** - Log all governance decisions and actions
+5. **PII scanning** - Use CK PIIDetector on prompts/responses
+
+## Deployment
+
+```bash
+# Deploy to Cloudflare Workers
+wrangler deploy
+
+# Bind required resources
+# - D1 database for agent state
+# - R2 bucket for file workspace
+# - Durable Object for governance
+# - Workers AI or external provider
+```