Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat(ruflo-deepseek-harness): function-hook mod (secret guard, /deepseek-harness-mod, status file)

ruv92a71ee1626c
diff --git a/plugins/ruflo-deepseek-harness/.claude-plugin/plugin.json b/plugins/ruflo-deepseek-harness/.claude-plugin/plugin.json
index c42bed5f52..f439eb2566 100644
--- a/plugins/ruflo-deepseek-harness/.claude-plugin/plugin.json
+++ b/plugins/ruflo-deepseek-harness/.claude-plugin/plugin.json
@@ -1,9 +1,35 @@
{
"name": "ruflo-deepseek-harness",
"description": "DeepSeek model harness for ruflo — agents, commands, scripts, and skills for running and evaluating DeepSeek-backed workflows within the ruflo swarm.",
- "version": "0.1.0",
- "author": { "name": "ruvnet", "url": "https://github.com/ruvnet" },
+ "version": "0.2.0",
+ "author": {
+ "name": "ruvnet",
+ "url": "https://github.com/ruvnet"
+ },
"homepage": "https://github.com/ruvnet/ruflo",
"license": "MIT",
- "keywords": ["ruflo", "deepseek", "harness", "llm", "agents", "skills"]
+ "keywords": [
+ "ruflo",
+ "deepseek",
+ "harness",
+ "llm",
+ "agents",
+ "skills",
+ "mod",
+ "function-hooks",
+ "guard"
+ ],
+ "userConfig": {
+ "guard": {
+ "type": "string",
+ "title": "Secret guard",
+ "description": "Refuse prompts sent to the DeepSeek API that hold a key, token or password. On by default; it only ever tightens.",
+ "required": false,
+ "default": "on",
+ "options": [
+ "on",
+ "off"
+ ]
+ }
+ }
}
diff --git a/plugins/ruflo-deepseek-harness/README.md b/plugins/ruflo-deepseek-harness/README.md
new file mode 100644
index 0000000000..dd185960fa
--- /dev/null
+++ b/plugins/ruflo-deepseek-harness/README.md
@@ -0,0 +1,14 @@
+# ruflo-deepseek-harness
+
+DeepSeek chat and reasoning completions as ruflo skills (see `commands/ruflo-deepseek-harness.md`).
+
+## As a mod
+
+Since this version the plugin is also a function-hook mod (ADR-445 pattern; needs Claude Code 2.1.287 or later). It never calls the network or spawns a process, and it only tightens: it can refuse a call, never allow one.
+
+- **Guard** (default on): refuses Bash commands that run this plugin's `chat.mjs`/`reason.mjs` (they post the prompt to api.deepseek.com) that hold a key, token or password. The reason names the kind of secret, never the value.
+- **`/deepseek-mod`**: answered locally, no model turn: `status`, `scan <text>` (would the guard refuse this?).
+- **Status file**: `.claude-flow/deepseek-mod/status.json` (`{version, updatedMs, guard, blocked}`), written at session start and when a call is blocked.
+- **Option**: `guard` (`on` | `off`, default `on`) in the plugin's `userConfig`.
+
+Test it: `claude plugin test plugins/ruflo-deepseek-harness` and `bash plugins/ruflo-deepseek-harness/scripts/smoke.sh`.
diff --git a/plugins/ruflo-deepseek-harness/hooks/command.ts b/plugins/ruflo-deepseek-harness/hooks/command.ts
new file mode 100644
index 0000000000..ed2495a29e
--- /dev/null
+++ b/plugins/ruflo-deepseek-harness/hooks/command.ts
@@ -0,0 +1,31 @@
+import type { FsEntry } from 'claude-code'
+
+import { secretNames } from './screen'
+import type { Stats } from './status'
+
+/** `/deepseek-mod` is answered locally and takes no model turn. Everything it reads is already connected; nothing is written. */
+export type CommandDeps = {
+ readonly guard: boolean
+ readonly stats: Stats
+ readonly tools: () => Promise<readonly string[]>
+ readonly list: (path: string) => Promise<readonly FsEntry[]>
+}
+
+const HELP = ['/deepseek-mod status', '/deepseek-mod scan <text>'].join('\n')
+
+export async function answer(args: string, deps: CommandDeps): Promise<string> {
+ const [verb = '', ...rest] = args.trim().split(/\s+/)
+ const arg = rest.join(' ')
+
+ if (verb === '' || verb === 'help') return HELP
+
+ if (verb === 'status') return `guard ${deps.guard ? 'on' : 'off'} · calls blocked ${deps.stats.blocked}`
+
+ if (verb === 'scan') {
+ if (arg === '') return 'usage: /deepseek-mod scan <text>'
+ const found = secretNames(arg)
+ return found.length ? `The guard would refuse that (${found.join(', ')}).` : 'Nothing found: the guard would let that through.'
+ }
+
+ return `Unknown: ${verb}\n${HELP}`
+}
diff --git a/plugins/ruflo-deepseek-harness/hooks/guard.ts b/plugins/ruflo-deepseek-harness/hooks/guard.ts
new file mode 100644
index 0000000000..6717a8076e
--- /dev/null
+++ b/plugins/ruflo-deepseek-harness/hooks/guard.ts
@@ -0,0 +1,14 @@
+import { hasSecret } from './screen'
+
+/** A shell command that runs this plugin's scripts: they post the prompt to api.deepseek.com, a third party. */
+const RUNS_HARNESS = /ruflo-deepseek-harness\/scripts\/(?:chat|reason|_deepseek)\.mjs/
+
+/** The reason a DeepSeek call is refused, or undefined when it may go. Never names or echoes the secret. */
+export function verdict(tool: string, input: unknown): string | undefined {
+ if (tool !== 'Bash') return undefined
+ const command = typeof input === 'object' && input !== null ? (input as { command?: unknown }).command : undefined
+ if (typeof command !== 'string' || !RUNS_HARNESS.test(command)) return undefined
+ return hasSecret(command)
+ ? 'ruflo-deepseek-harness: this prompt holds what looks like a secret (a key, token or password) and would be sent to api.deepseek.com. Remove it and run again.'
+ : undefined
+}
diff --git a/plugins/ruflo-deepseek-harness/hooks/hooks.json b/plugins/ruflo-deepseek-harness/hooks/hooks.json
new file mode 100644
index 0000000000..0146b0dc50
--- /dev/null
+++ b/plugins/ruflo-deepseek-harness/hooks/hooks.json
@@ -0,0 +1,4 @@
+{
+ "description": "DeepSeek harness as a mod: a guard that keeps secrets out of prompts sent to the DeepSeek API, /deepseek-mod, and a status file.",
+ "modules": ["./register.ts"]
+}
diff --git a/plugins/ruflo-deepseek-harness/hooks/options.ts b/plugins/ruflo-deepseek-harness/hooks/options.ts
new file mode 100644
index 0000000000..e18352b921
--- /dev/null
+++ b/plugins/ruflo-deepseek-harness/hooks/options.ts
@@ -0,0 +1,9 @@
+import type { PluginOptions } from 'claude-code'
+
+/** The plugin's `userConfig`, validated: a bad value is the default (guard on). */
+export type ModOptions = { readonly guard: boolean }
+
+const flag = (value: unknown, fallback: boolean) =>
+ value === true || value === 'true' || value === 'on' ? true : value === false || value === 'false' || value === 'off' ? false : fallback
+
+export const readOptions = (options: PluginOptions | undefined): ModOptions => ({ guard: flag((options ?? {}).guard, true) })
diff --git a/plugins/ruflo-deepseek-harness/hooks/register.ts b/plugins/ruflo-deepseek-harness/hooks/register.ts
new file mode 100644
index 0000000000..3b633bf85f
--- /dev/null
+++ b/plugins/ruflo-deepseek-harness/hooks/register.ts
@@ -0,0 +1,62 @@
+import type { Hook, Register } from 'claude-code'
+
+import { answer } from './command'
+import { verdict } from './guard'
+import { readOptions, type ModOptions } from './options'
+import { newStats, STATUS_PATH, statusText, type Stats } from './status'
+
+type Dollar = Parameters<Hook<'session.start'>>[0]
+
+/** Everything one session of the mod keeps: its settings, counters and the project root. */
+type Session = { readonly opts: ModOptions; readonly stats: Stats; root?: string }
+
+async function flush($: Dollar, s: Session): Promise<void> {
+ if (s.root === undefined) return
+ try {
+ await $.fs.write(`${s.root}/${STATUS_PATH}`, statusText(s.stats, s.opts.guard, await $.clock.now()))
+ } catch {
+ /* the status file is a courtesy */
+ }
+}
+
+/**
+ * ruflo-deepseek-harness as a mod (ADR-445 pattern): a tighten-only guard on this plugin's own tools, `/deepseek-mod` and a status file. No network, no process
+ * spawning: only tools already connected.
+ */
+export const register: Register = (on, options) => {
+ const s: Session = { opts: readOptions(options), stats: newStats() }
+
+ on('session.start', async ($, e, next) => {
+ const result = await next(e)
+ s.root = (await $.session.root()) as string | undefined
+ try {
+ await $.command.register({ name: 'deepseek-mod', description: 'ruflo-deepseek-harness mod: status, scan <text>, plus a read-only listing' })
+ } catch {
+ /* a name taken by another plugin must not stop the mod */
+ }
+ await flush($, s)
+ return result
+ })
+
+ if (s.opts.guard) {
+ on('tool.call', async ($, e, next) => {
+ const reason = verdict(e.tool, e)
+ if (reason === undefined) return next(e)
+ s.stats.blocked++
+ await flush($, s)
+ return { deny: reason }
+ })
+ }
+
+ /** `/deepseek-mod` is answered locally and takes no model turn. */
+ on('command.run', { command: 'deepseek-mod' }, async ($, e) => {
+ const args = typeof e.args === 'string' ? e.args : ''
+ const text = await answer(args, {
+ guard: s.opts.guard,
+ stats: s.stats,
+ tools: async () => (await $.tool.list()).map(t => t.name),
+ list: path => $.fs.list(path),
+ })
+ return { text }
+ })
+}
diff --git a/plugins/ruflo-deepseek-harness/hooks/screen.ts b/plugins/ruflo-deepseek-harness/hooks/screen.ts
new file mode 100644
index 0000000000..14e017efed
--- /dev/null
+++ b/plugins/ruflo-deepseek-harness/hooks/screen.ts
@@ -0,0 +1,41 @@
+/**
+ * Pure secret screening for this mod (copied from ruflo-agentdb's ADR-445 screen.ts, injection rules dropped). Findings are NAMES only: the
+ * matched text is never returned, logged or counted by value.
+ */
+
+const SECRETS: readonly (readonly [string, RegExp])[] = [
+ ['private key', /-----BEGIN [A-Z ]*PRIVATE KEY-----/],
+ ['aws access key', /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/],
+ ['github token', /\b(?:gh[pousr]_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{40,})\b/],
+ ['slack token', /\bxox[abprs]-[A-Za-z0-9-]{10,}/],
+ ['google api key', /\bAIza[0-9A-Za-z_-]{35}\b/],
+ ['anthropic or openai key', /\bsk-(?:ant-|proj-)?[A-Za-z0-9_-]{24,}/],
+ ['jwt', /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/],
+ ['bearer token', /\bBearer\s+[A-Za-z0-9._~+/=-]{24,}/],
+ ['key assignment', /\b(?:api[_-]?key|secret|token|passw(?:or)?d|credential)s?["']?\s*[:=]\s*["']?[A-Za-z0-9/+=_.-]{16,}/i],
+]
+
+// C0/C1 controls (keeping tab and newline), DEL, zero-width and bidi override characters; built with escapes, never raw.
+const INVISIBLE = new RegExp('[\\u0000-\\u0008\\u000b-\\u001f\\u007f-\\u009f\\u200b-\\u200f\\u2028-\\u202e\\u2060-\\u2064\\ufeff]', 'g')
+
+const bare = (text: string) => (text.length > 20_000 ? text.slice(0, 20_000) : text).replace(INVISIBLE, '')
+
+/** Names of every secret shape found in `text`. Cost is linear in the capped input. */
+export const secretNames = (text: string): string[] => {
+ const bounded = bare(text)
+ return SECRETS.filter(([, re]) => re.test(bounded)).map(([name]) => name)
+}
+
+export const hasSecret = (text: string) => secretNames(text).length > 0
+
+/** Every string in a tool's input, to a bounded depth and size: what a guard reads. */
+export function textsOf(input: unknown, budget = { left: 20_000 }, depth = 0): string[] {
+ if (budget.left <= 0 || depth > 6) return []
+ if (typeof input === 'string') {
+ budget.left -= input.length
+ return [input]
+ }
+ if (Array.isArray(input)) return input.slice(0, 200).flatMap(v => textsOf(v, budget, depth + 1))
+ if (typeof input === 'object' && input !== null) return Object.values(input).slice(0, 200).flatMap(v => textsOf(v, budget, depth + 1))
+ return []
+}
diff --git a/plugins/ruflo-deepseek-harness/hooks/status.ts b/plugins/ruflo-deepseek-harness/hooks/status.ts
new file mode 100644
index 0000000000..5c4cdc1a57
--- /dev/null
+++ b/plugins/ruflo-deepseek-harness/hooks/status.ts
@@ -0,0 +1,10 @@
+/** Counters the mod keeps for the session and writes to `.claude-flow/deepseek-mod/status.json`. */
+export type Stats = { blocked: number }
+
+export const newStats = (): Stats => ({ blocked: 0 })
+
+export const STATUS_PATH = '.claude-flow/deepseek-mod/status.json'
+
+/** The file's text; `version` lets a reader refuse a shape it does not know. */
+export const statusText = (stats: Stats, guard: boolean, nowMs: number): string =>
+ `${JSON.stringify({ version: 1, updatedMs: nowMs, guard, ...stats }, null, 2)}\n`
diff --git a/plugins/ruflo-deepseek-harness/scripts/smoke.sh b/plugins/ruflo-deepseek-harness/scripts/smoke.sh
new file mode 100755
index 0000000000..2af73192bb
--- /dev/null
+++ b/plugins/ruflo-deepseek-harness/scripts/smoke.sh
@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Structural smoke test for ruflo-deepseek-harness: the plugin's scripts exist, and the mod (ADR-445 pattern) is wired.
+set -u
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PASS=0
+FAIL=0
+
+step() { printf "→ %s ... " "$1"; }
+ok() { printf "PASS\n"; PASS=$((PASS+1)); }
+bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
+
+step "1. plugin.json declares version 0.2.0"
+grep -q '"version": "0.2.0"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "version is not 0.2.0"
+
+step "2. scripts, both skills, the command and the agent are present"
+miss=""
+for f in scripts/_deepseek.mjs scripts/chat.mjs scripts/reason.mjs skills/deepseek-chat/SKILL.md skills/deepseek-reason/SKILL.md commands/ruflo-deepseek-harness.md agents/deepseek-architect.md; do
+ [[ -f "$ROOT/$f" ]] || miss="$miss $f"
+done
+[[ -z "$miss" ]] && ok || bad "missing:$miss"
+
+# M1. The mod (ADR-445 pattern): hooks module registered, files within the 500-line rule, no network or process access in the hooks
+step "M1. mod: hooks.json names register.ts, every hook file is present and under 500 lines"
+mod_ok=1
+grep -q '"./register.ts"' "$ROOT/hooks/hooks.json" || mod_ok=0
+for f in options screen guard command status register; do
+ [[ -f "$ROOT/hooks/$f.ts" ]] || mod_ok=0
+ [[ $(wc -l < "$ROOT/hooks/$f.ts" 2>/dev/null || echo 9999) -le 500 ]] || mod_ok=0
+done
+[[ $mod_ok -eq 1 ]] && ok || bad "mod hooks incomplete or too long"
+
+step "M2. mod: guard defaults on, and it is the only userConfig option"
+node -e '
+const c = require(process.argv[1]).userConfig || {}
+process.exit(c.guard && c.guard.default === "on" && Object.keys(c).length === 1 ? 0 : 1)
+' "$ROOT/.claude-plugin/plugin.json" && ok || bad "userConfig defaults wrong"
+
+step "M3. mod: hooks never touch the network or spawn a process"
+if grep -nE '\$\.(http|process)\.|child_process|fetch\(' "$ROOT"/hooks/*.ts >/dev/null; then bad "network or process call in hooks"; else ok; fi
+
+printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"
+[[ $FAIL -eq 0 ]] || exit 1
diff --git a/plugins/ruflo-deepseek-harness/tests/mod.test.ts b/plugins/ruflo-deepseek-harness/tests/mod.test.ts
new file mode 100644
index 0000000000..2102ebdb8a
--- /dev/null
+++ b/plugins/ruflo-deepseek-harness/tests/mod.test.ts
@@ -0,0 +1,84 @@
+import type { On } from 'claude-code'
+import { describe, expect, test, tier } from 'claude-code/testing'
+
+tier('user')
+
+const ROOT = '/work'
+const START = { surface: 'terminal', isInteractive: true, cwd: ROOT } as const
+const slash = (args: string) => ({ command: 'deepseek-mod', args, origin: { kind: 'composer' }, presentation: { isFullscreen: false, columns: 100 } }) as const
+const STATUS = `${ROOT}/.claude-flow/deepseek-mod/status.json`
+const SECRET = `ghp_${'a1B2'.repeat(10)}`
+
+/** The world beneath the mod: a project root, a file map, a tool list and a directory map. */
+function world(on: On, tools: readonly string[] = [], dirs: Record<string, { name: string; kind: 'file' | 'dir'; mtimeMs?: number }[]> = {}) {
+ const files = new Map<string, string>()
+ on('session.start', ($, e) => ({ cwd: e.cwd }))
+ on('session.root', () => ({ value: ROOT }))
+ on('command.register', ($, e) => ({ value: { command: e.name } }))
+ on('fs.write', ($, e) => (files.set(e.path, e.text), { value: undefined }))
+ on('fs.list', ($, e) => {
+ const key = Object.keys(dirs).find(k => e.path === k || e.path.endsWith(`/${k}`))
+ const entries = key === undefined ? undefined : dirs[key]
+ if (!entries) throw new Error('ENOENT')
+ return { value: entries.map(x => ({ size: 0, mtimeMs: 0, isLink: false, ...x })) }
+ })
+ on('tool.list', () => ({ value: tools.map(name => ({ name, description: '', mcp: true })) }))
+ on('clock.now', () => ({ value: 1_700_000_000_000 }))
+ return { files }
+}
+
+const call = (input: Record<string, unknown>) => input as never
+const denied = (r: unknown) => JSON.stringify(r)
+
+describe('guard', () => {
+ test('refuses a secret, never echoes it, and counts the block in the status file', async ($, on) => {
+ const w = world(on)
+ on('tool.call', () => ({ result: 'went through' }))
+ await $.session.start(START)
+ const r = await $.tool.call(call(((s: string) => ({ tool: 'Bash', command: `node plugins/ruflo-deepseek-harness/scripts/chat.mjs --prompt "use ${s}"` }))(SECRET))).then(
+ x => x,
+ (e: unknown) => ({ text: String(e) }),
+ )
+ expect(denied(r)).toContain('ruflo-')
+ expect(denied(r)).not.toContain('went through')
+ expect(denied(r)).not.toContain('ghp_')
+ expect(JSON.parse(w.files.get(STATUS) ?? '{}')).toMatchObject({ version: 1, guard: true, blocked: 1 })
+ })
+
+ test('passes clean input and tools the plugin does not own', async ($, on) => {
+ world(on)
+ on('tool.call', () => ({ result: 'went through' }))
+ await $.session.start(START)
+ expect(denied(await $.tool.call(call({ tool: 'Bash', command: 'node plugins/ruflo-deepseek-harness/scripts/chat.mjs --prompt "hello"' })))).toContain('went through')
+ expect(denied(await $.tool.call(call({ tool: 'Read', file_path: `/tmp/${SECRET}` })))).toContain('went through')
+ })
+
+ test('guard: off lets the call through', { options: { guard: 'off' } }, async ($, on) => {
+ world(on)
+ on('tool.call', () => ({ result: 'went through' }))
+ await $.session.start(START)
+ expect(denied(await $.tool.call(call(((s: string) => ({ tool: 'Bash', command: `node plugins/ruflo-deepseek-harness/scripts/chat.mjs --prompt "use ${s}"` }))(SECRET))))).toContain('went through')
+ })
+})
+
+describe('status file', () => {
+ test('is written at session start with the defaults', async ($, on) => {
+ const w = world(on)
+ await $.session.start(START)
+ expect(JSON.parse(w.files.get(STATUS) ?? '{}')).toEqual({ version: 1, updatedMs: 1_700_000_000_000, guard: true, blocked: 0 })
+ })
+})
+
+describe('/deepseek-mod', () => {
+ test('status and scan answer locally, and help is the fallback', async ($, on) => {
+ world(on)
+ await $.session.start(START)
+ expect((await $.command.run(slash('status'))).text).toBe('guard on · calls blocked 0')
+ expect((await $.command.run(slash(`scan key ${SECRET}`))).text).toContain('github token')
+ expect((await $.command.run(slash(`scan key ${SECRET}`))).text).not.toContain('ghp_')
+ expect((await $.command.run(slash('scan plain words'))).text).toContain('Nothing found')
+ expect((await $.command.run(slash(''))).text).toContain('/deepseek-mod scan <text>')
+ expect((await $.command.run(slash('what is this'))).text).toContain('Unknown: what')
+ })
+
+})
diff --git a/plugins/ruflo-deepseek-harness/tsconfig.json b/plugins/ruflo-deepseek-harness/tsconfig.json
new file mode 100644
index 0000000000..e4ba54993e
--- /dev/null
+++ b/plugins/ruflo-deepseek-harness/tsconfig.json
@@ -0,0 +1,19 @@
+{
+ "//": "Self-contained on purpose: bundlers (vite/esbuild in the root CI vitest) load this file for every module they transform, so it must not extend a file that only exists after Claude Code (>= 2.1.287) has loaded the plugin. Claude Code writes its declarations to .claude-plugin/types/ (gitignored) on load or validate; tsc -p . then reads them through typeRoots.",
+ "compilerOptions": {
+ "target": "es2023",
+ "lib": ["es2023"],
+ "module": "esnext",
+ "moduleResolution": "bundler",
+ "strict": true,
+ "noUncheckedIndexedAccess": true,
+ "noEmit": true,
+ "skipLibCheck": true,
+ "jsx": "react",
+ "jsxFactory": "h",
+ "jsxFragmentFactory": "Fragment",
+ "typeRoots": ["./.claude-plugin/types"],
+ "types": ["claude-code", "claude-code-tools", "claude-code-mcp"]
+ },
+ "include": ["hooks", "tests"]
+}