Files
marqdo/plugins/agent/src/tools.rs
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

795 lines
27 KiB
Rust
Executable File

//! ToolSpecV1 registry + call validation (M-A2).
//! Discovery → schema validate → authorize. Execution of Marqdo `##` stays in subtask;
//! this module never evals model-supplied code.
use std::collections::HashMap;
use std::sync::{Mutex, OnceLock};
use serde_json::{json, Map, Value};
fn registry() -> &'static Mutex<HashMap<String, Value>> {
static REG: OnceLock<Mutex<HashMap<String, Value>>> = OnceLock::new();
REG.get_or_init(|| Mutex::new(HashMap::new()))
}
fn opt_text<'a>(args: &'a Value, key: &str) -> Option<&'a str> {
args.get(key)
.and_then(|v| v.as_str())
.filter(|s| !s.is_empty())
}
fn arg_text<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> {
opt_text(args, key).ok_or_else(|| format!("missing text `{key}`"))
}
/// Supported JSON Schema subset for tool input (reject unsupported constructs).
fn validate_schema_subset(schema: &Value) -> Result<(), String> {
let obj = schema
.as_object()
.ok_or_else(|| "input_schema must be object".to_string())?;
let ty = obj
.get("type")
.and_then(|v| v.as_str())
.unwrap_or("object");
if ty != "object" {
return Err(format!("unsupported root type={ty}; only object"));
}
if let Some(props) = obj.get("properties") {
let props = props
.as_object()
.ok_or_else(|| "properties must be object".to_string())?;
for (name, prop) in props {
let p = prop
.as_object()
.ok_or_else(|| format!("property {name} must be object"))?;
let pty = p.get("type").and_then(|v| v.as_str()).unwrap_or("string");
match pty {
"string" | "integer" | "number" | "boolean" | "array" | "object" => {}
other => {
return Err(format!(
"unsupported property type {other} for {name}; refuse register"
))
}
}
// Reject constructs we do not implement.
for banned in ["$ref", "oneOf", "anyOf", "allOf", "not", "if", "then", "else"] {
if p.contains_key(banned) {
return Err(format!(
"unsupported schema keyword {banned} on {name}; refuse register"
));
}
}
}
}
for banned in ["$ref", "oneOf", "anyOf", "allOf", "not", "if", "then", "else"] {
if obj.contains_key(banned) {
return Err(format!(
"unsupported schema keyword {banned}; refuse register"
));
}
}
Ok(())
}
fn normalize_spec(mut spec: Value) -> Result<Value, String> {
let obj = spec
.as_object_mut()
.ok_or_else(|| "spec must be object".to_string())?;
obj.insert("schema".into(), json!("ToolSpecV1"));
obj.entry("schema_version".to_string())
.or_insert(json!(1));
let id = obj
.get("id")
.and_then(|v| v.as_str())
.filter(|s| !s.is_empty())
.ok_or_else(|| "ToolSpecV1 requires id".to_string())?
.to_string();
obj.entry("version".to_string()).or_insert(json!("1"));
obj.entry("description".to_string())
.or_insert(json!(""));
let input = obj
.get("input_schema")
.cloned()
.unwrap_or_else(|| json!({"type": "object", "properties": {}, "additionalProperties": false}));
validate_schema_subset(&input)?;
obj.insert("input_schema".into(), input);
obj.entry("effect".to_string()).or_insert(json!("read"));
let effect = obj.get("effect").and_then(|v| v.as_str()).unwrap_or("read");
if !matches!(effect, "read" | "write" | "execute" | "external_write") {
return Err(format!("invalid effect={effect}"));
}
obj.entry("scopes".to_string()).or_insert(json!([]));
obj.entry("timeout_ms".to_string()).or_insert(json!(10_000));
obj.entry("max_result_bytes".to_string())
.or_insert(json!(65_536));
obj.entry("idempotency".to_string())
.or_insert(json!("safe"));
obj.entry("availability".to_string())
.or_insert(json!("ready"));
let _ = id;
Ok(spec)
}
fn validate_args_against_schema(schema: &Value, arguments: &Value) -> Result<(), String> {
let args = arguments
.as_object()
.ok_or_else(|| "arguments must be object".to_string())?;
let sch = schema.as_object().ok_or_else(|| "input_schema invalid".to_string())?;
let props = sch
.get("properties")
.and_then(|v| v.as_object())
.cloned()
.unwrap_or_default();
let additional = sch
.get("additionalProperties")
.and_then(|v| v.as_bool())
.unwrap_or(true);
if !additional {
for key in args.keys() {
if !props.contains_key(key) {
return Err(format!("unknown argument `{key}`"));
}
}
}
if let Some(req) = sch.get("required").and_then(|v| v.as_array()) {
for r in req {
let name = r.as_str().unwrap_or("");
if name.is_empty() {
continue;
}
if !args.contains_key(name) || args.get(name).map(|v| v.is_null()).unwrap_or(true) {
return Err(format!("missing required argument `{name}`"));
}
}
}
for (key, val) in args {
if let Some(prop) = props.get(key) {
if let Some(pty) = prop.get("type").and_then(|v| v.as_str()) {
let ok = match pty {
"string" => val.is_string(),
"integer" => val.as_i64().is_some() || val.as_u64().is_some(),
"number" => val.as_f64().is_some(),
"boolean" => val.is_boolean(),
"array" => val.is_array(),
"object" => val.is_object(),
_ => true,
};
if !ok {
return Err(format!("argument `{key}` type mismatch (want {pty})"));
}
}
if let Some(min) = prop.get("minimum").and_then(|v| v.as_f64()) {
if let Some(n) = val.as_f64() {
if n < min {
return Err(format!("argument `{key}` below minimum {min}"));
}
}
}
if let Some(max) = prop.get("maximum").and_then(|v| v.as_f64()) {
if let Some(n) = val.as_f64() {
if n > max {
return Err(format!("argument `{key}` above maximum {max}"));
}
}
}
}
}
Ok(())
}
fn authorized(allowlist: Option<&Value>, tool_id: &str) -> bool {
match allowlist {
None => true, // registry-only call sites may omit; still need registered spec
Some(tools) => crate::tool_names(tools).iter().any(|n| n == tool_id),
}
}
/// Register one ToolSpecV1 (or list). Host/trusted only — model cannot invent principal/root.
pub fn tools_register(args: &Value) -> Result<Value, String> {
let specs = if let Some(arr) = args.get("specs").and_then(|v| v.as_array()) {
arr.clone()
} else if args.get("spec").is_some() || args.get("id").is_some() {
let raw = args.get("spec").cloned().unwrap_or_else(|| args.clone());
vec![raw]
} else {
return Err("tools.register requires spec or specs[]".into());
};
let mut registered = Vec::new();
let mut guard = registry()
.lock()
.map_err(|_| "tools registry lock poisoned".to_string())?;
for raw in specs {
let spec = normalize_spec(raw)?;
let id = spec
.get("id")
.and_then(|v| v.as_str())
.unwrap()
.to_string();
guard.insert(id.clone(), spec);
registered.push(id);
}
Ok(json!({
"ok": true,
"registered": registered,
"count": registered.len(),
}))
}
pub fn tools_clear(args: &Value) -> Result<Value, String> {
let _ = args;
let mut guard = registry()
.lock()
.map_err(|_| "tools registry lock poisoned".to_string())?;
let n = guard.len();
guard.clear();
Ok(json!({"ok": true, "cleared": n}))
}
pub fn tools_search(args: &Value) -> Result<Value, String> {
let query = opt_text(args, "query").unwrap_or("").to_ascii_lowercase();
let allow = args.get("tools");
let guard = registry()
.lock()
.map_err(|_| "tools registry lock poisoned".to_string())?;
let mut items = Vec::new();
for (id, spec) in guard.iter() {
let avail = spec
.get("availability")
.and_then(|v| v.as_str())
.unwrap_or("ready");
let auth = authorized(allow, id);
if !auth {
// Do not leak unauthorized private connector names in search hits.
continue;
}
if !query.is_empty() {
let desc = spec
.get("description")
.and_then(|v| v.as_str())
.unwrap_or("");
if !id.to_ascii_lowercase().contains(&query)
&& !desc.to_ascii_lowercase().contains(&query)
{
continue;
}
}
items.push(json!({
"id": id,
"version": spec.get("version").cloned().unwrap_or(json!("1")),
"description": spec.get("description").cloned().unwrap_or(json!("")),
"effect": spec.get("effect").cloned().unwrap_or(json!("read")),
"availability": avail,
"authorized": true,
}));
}
items.sort_by(|a, b| {
let ai = a.get("id").and_then(|v| v.as_str()).unwrap_or("");
let bi = b.get("id").and_then(|v| v.as_str()).unwrap_or("");
ai.cmp(bi)
});
Ok(json!({
"ok": true,
"schema": "ToolSearchResultV1",
"schema_version": 1,
"items": items,
"count": items.len(),
}))
}
pub fn tools_describe(args: &Value) -> Result<Value, String> {
let id = arg_text(args, "id")?;
let allow = args.get("tools");
if !authorized(allow, id) {
return Ok(json!({
"ok": false,
"found": false,
"authorized": false,
"error": {
"schema": "AgentErrorV1",
"schema_version": 1,
"code": "tool.forbidden",
"category": "forbidden",
"stage": "tool",
"message": format!("tool `{id}` not in allowlist"),
"retryable": false,
"effect_state": "none",
"recovery_action": "needs_input",
}
}));
}
let guard = registry()
.lock()
.map_err(|_| "tools registry lock poisoned".to_string())?;
match guard.get(id) {
Some(spec) => Ok(json!({
"ok": true,
"found": true,
"authorized": true,
"spec": spec,
})),
None => Ok(json!({
"ok": false,
"found": false,
"authorized": true,
"error": {
"schema": "AgentErrorV1",
"schema_version": 1,
"code": "tool.not_found",
"category": "capability_unavailable",
"stage": "tool",
"message": format!("tool `{id}` not registered"),
"retryable": false,
"effect_state": "none",
"recovery_action": "stop",
}
})),
}
}
/// Validate + authorize a ToolCallV1. Does not execute side effects.
pub fn tools_prepare_call(args: &Value) -> Result<Value, String> {
let tool_id = arg_text(args, "tool_id")
.or_else(|_| arg_text(args, "id"))
.or_else(|_| arg_text(args, "name"))?;
let allow = args.get("tools");
if !authorized(allow, tool_id) {
return Ok(tool_result_err(
"tool.forbidden",
"forbidden",
format!("unauthorized call to `{tool_id}`"),
false,
));
}
let guard = registry()
.lock()
.map_err(|_| "tools registry lock poisoned".to_string())?;
let spec = match guard.get(tool_id) {
Some(s) => s.clone(),
None => {
return Ok(tool_result_err(
"tool.not_found",
"capability_unavailable",
format!("tool `{tool_id}` not registered"),
false,
));
}
};
drop(guard);
let avail = spec
.get("availability")
.and_then(|v| v.as_str())
.unwrap_or("ready");
if avail != "ready" {
return Ok(tool_result_err(
"tool.unavailable",
"capability_unavailable",
format!("tool `{tool_id}` availability={avail}"),
false,
));
}
let arguments = match args.get("arguments") {
None | Some(Value::Null) => json!({}),
Some(v) => v.clone(),
};
let schema = spec
.get("input_schema")
.cloned()
.unwrap_or_else(|| json!({"type":"object"}));
if let Err(e) = validate_args_against_schema(&schema, &arguments) {
return Ok(tool_result_err(
"tool.invalid_arguments",
"invalid_arguments",
e,
true,
));
}
let call_id = opt_text(args, "call_id")
.map(|s| s.to_string())
.unwrap_or_else(|| format!("call_{}", std::process::id()));
let operation_id = opt_text(args, "operation_id")
.map(|s| s.to_string())
.unwrap_or_else(|| format!("op_{tool_id}_{call_id}"));
let version = spec
.get("version")
.and_then(|v| v.as_str())
.unwrap_or("1");
let effect = spec
.get("effect")
.and_then(|v| v.as_str())
.unwrap_or("read");
let digest = args_digest(&arguments);
let logical_run = opt_text(args, "logical_run_id").unwrap_or("-");
let step = opt_text(args, "step_id").unwrap_or("-");
let idempotency_key = opt_text(args, "idempotency_key")
.map(|s| s.to_string())
.unwrap_or_else(|| format!("{logical_run}|{step}|{tool_id}|{digest}"));
let needs_ledger = matches!(effect, "write" | "execute" | "external_write");
let call = json!({
"schema": "ToolCallV1",
"schema_version": 1,
"call_id": call_id,
"tool_id": tool_id,
"tool_version": version,
"arguments": arguments,
"operation_id": operation_id,
"parent_span_id": args.get("parent_span_id").cloned().unwrap_or(Value::Null),
});
Ok(json!({
"ok": true,
"status": "prepared",
"call": call,
"spec": {
"id": tool_id,
"effect": effect,
"timeout_ms": spec.get("timeout_ms").cloned().unwrap_or(json!(10000)),
"max_result_bytes": spec.get("max_result_bytes").cloned().unwrap_or(json!(65536)),
},
"args_digest": digest,
"idempotency_key": idempotency_key,
"needs_ledger": needs_ledger,
"summary": format!("prepared authorized call to `{tool_id}`"),
}))
}
/// Stable digest of tool arguments for effect ledger idempotency (M-A5a).
pub fn tools_args_digest(args: &Value) -> Result<Value, String> {
let arguments = args
.get("arguments")
.cloned()
.or_else(|| args.get("value").cloned())
.unwrap_or_else(|| json!({}));
Ok(json!({
"ok": true,
"args_digest": args_digest(&arguments),
}))
}
fn args_digest(arguments: &Value) -> String {
let text = serde_json::to_string(arguments).unwrap_or_else(|_| "{}".into());
format!("sha256-lite:{:x}", fnv1a64(&text))
}
fn fnv1a64(s: &str) -> u64 {
let mut h: u64 = 0xcbf29ce484222325;
for b in s.as_bytes() {
h ^= u64::from(*b);
h = h.wrapping_mul(0x100000001b3);
}
h
}
/// True when effect_class requires EffectLedger before/after execution.
pub fn tools_needs_ledger(args: &Value) -> Result<Value, String> {
let effect = opt_text(args, "effect")
.or_else(|| opt_text(args, "effect_class"))
.unwrap_or("read");
Ok(json!({
"ok": true,
"needs_ledger": matches!(effect, "write" | "execute" | "external_write"),
"effect": effect,
}))
}
/// Wrap a successful / failed tool execution into ToolResultV1.
pub fn tools_wrap_result(args: &Value) -> Result<Value, String> {
let ok = args.get("ok").and_then(|v| v.as_bool()).unwrap_or(false);
let status = opt_text(args, "status").unwrap_or(if ok { "succeeded" } else { "failed" });
let summary = opt_text(args, "summary").unwrap_or("");
let mut out = json!({
"schema": "ToolResultV1",
"schema_version": 1,
"ok": ok,
"status": status,
"summary": summary,
"structured_content": args.get("structured_content").cloned().unwrap_or(Value::Null),
"resources": args.get("resources").cloned().unwrap_or_else(|| json!([])),
"citations": args.get("citations").cloned().unwrap_or_else(|| json!([])),
"error": args.get("error").cloned().unwrap_or(Value::Null),
"usage": args.get("usage").cloned().unwrap_or(Value::Null),
"truncated": args.get("truncated").and_then(|v| v.as_bool()).unwrap_or(false),
"next_cursor": args.get("next_cursor").cloned().unwrap_or(Value::Null),
"effect_receipt_ref": args.get("effect_receipt_ref").cloned().unwrap_or(Value::Null),
});
// Truncate oversized summary into artifact hint (do not dump MB into prompt).
let max_bytes = args
.get("max_result_bytes")
.and_then(|v| v.as_u64())
.unwrap_or(65_536) as usize;
if summary.len() > max_bytes {
if let Some(obj) = out.as_object_mut() {
obj.insert("truncated".into(), json!(true));
obj.insert(
"summary".into(),
json!(format!(
"{}… [truncated; use resource handle]",
&summary[..max_bytes.min(summary.len())]
)),
);
}
}
Ok(out)
}
/// Seed the five engineering tools used by qdagent (aliases remain CALL:tool_*).
pub fn tools_register_eng_defaults(args: &Value) -> Result<Value, String> {
let _ = args;
let specs = eng_default_specs();
tools_register(&json!({"specs": specs}))
}
fn eng_default_specs() -> Vec<Value> {
vec![
json!({
"id": "tool_find",
"version": "1",
"description": "Engineering find via EKC (read-only)",
"input_schema": {
"type": "object",
"properties": {"query": {"type": "string"}},
"required": ["query"],
"additionalProperties": false
},
"effect": "read",
"scopes": ["knowledge:read"],
"availability": "ready"
}),
json!({
"id": "tool_reuse",
"version": "1",
"description": "Engineering reuse / preflight discovery (read-only)",
"input_schema": {
"type": "object",
"properties": {"task": {"type": "string"}},
"required": ["task"],
"additionalProperties": false
},
"effect": "read",
"scopes": ["knowledge:read"],
"availability": "ready"
}),
json!({
"id": "tool_bind",
"version": "1",
"description": "Bind and execute a verified knowledge artifact",
"input_schema": {
"type": "object",
"properties": {
"query": {"type": "string"},
"policy": {"type": "string"},
"project": {"type": "string"}
},
"required": ["query"],
"additionalProperties": false
},
"effect": "execute",
"scopes": ["knowledge:execute"],
"availability": "ready"
}),
json!({
"id": "tool_verify",
"version": "1",
"description": "Run L3 knowledge verification checks",
"input_schema": {
"type": "object",
"properties": {},
"additionalProperties": false
},
"effect": "read",
"scopes": ["knowledge:verify"],
"availability": "ready"
}),
json!({
"id": "tool_summarize",
"version": "1",
"description": "Summarize a Context Pack / preflight map",
"input_schema": {
"type": "object",
"properties": {"preflight": {"type": "object"}},
"required": ["preflight"],
"additionalProperties": false
},
"effect": "read",
"scopes": ["knowledge:read"],
"availability": "ready"
}),
]
}
fn tool_result_err(code: &str, category: &str, message: String, retryable: bool) -> Value {
let recovery = if category == "invalid_arguments" {
"repair_args"
} else if category == "forbidden" {
"needs_input"
} else {
"stop"
};
json!({
"ok": false,
"status": "failed",
"summary": message,
"schema": "ToolResultV1",
"schema_version": 1,
"structured_content": null,
"resources": [],
"citations": [],
"error": {
"schema": "AgentErrorV1",
"schema_version": 1,
"code": code,
"category": category,
"stage": "tool",
"message": message,
"retryable": retryable,
"retry_after_ms": null,
"effect_state": "none",
"recovery_action": recovery,
},
"usage": null,
"truncated": false,
"next_cursor": null,
"effect_receipt_ref": null,
})
}
/// Seed stub specs from a CALL allowlist (args.tools).
pub fn seed_from_allowlist_args(args: &Value) -> Result<Value, String> {
let tools = args
.get("tools")
.ok_or_else(|| "tools.seed_allowlist requires tools".to_string())?;
seed_from_allowlist(tools)
}
fn seed_from_allowlist(tools: &Value) -> Result<Value, String> {
let names = crate::tool_names(tools);
let mut specs = Vec::new();
for name in names {
// Minimal stub if not already registered — CALL whitelist compatibility.
let already = {
let guard = registry()
.lock()
.map_err(|_| "tools registry lock poisoned".to_string())?;
guard.contains_key(&name)
};
if already {
continue;
}
let mut m = Map::new();
m.insert("id".into(), json!(name));
m.insert("version".into(), json!("1"));
m.insert(
"description".into(),
json!(format!("Allowlist-derived tool `{name}`")),
);
m.insert(
"input_schema".into(),
json!({"type":"object","properties":{},"additionalProperties":true}),
);
m.insert("effect".into(), json!("execute"));
m.insert("scopes".into(), json!(["call:allowlist"]));
m.insert("availability".into(), json!("ready"));
specs.push(Value::Object(m));
}
if specs.is_empty() {
return Ok(json!({"ok": true, "registered": [], "count": 0}));
}
tools_register(&json!({"specs": specs}))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn register_search_describe_and_forbid() {
let _ = tools_clear(&json!({}));
let reg = tools_register_eng_defaults(&json!({})).unwrap();
assert_eq!(reg["count"], 5);
let allow = json!(["tool_find", "tool_reuse"]);
let search = tools_search(&json!({"tools": allow, "query": "find"})).unwrap();
assert_eq!(search["count"], 1);
assert_eq!(search["items"][0]["id"], "tool_find");
// Unauthorized tool must not appear.
let search2 = tools_search(&json!({"tools": allow, "query": "bind"})).unwrap();
assert_eq!(search2["count"], 0);
let denied = tools_describe(&json!({"id": "tool_bind", "tools": allow})).unwrap();
assert_eq!(denied["authorized"], false);
assert_eq!(denied["ok"], false);
let ok = tools_describe(&json!({"id": "tool_find", "tools": allow})).unwrap();
assert_eq!(ok["found"], true);
assert_eq!(ok["spec"]["schema"], "ToolSpecV1");
}
#[test]
fn prepare_rejects_bad_args_and_unauthorized() {
let _ = tools_clear(&json!({}));
tools_register_eng_defaults(&json!({})).unwrap();
let allow = json!(["tool_find"]);
let bad = tools_prepare_call(&json!({
"tool_id": "tool_find",
"tools": allow,
"arguments": {}
}))
.unwrap();
assert_eq!(bad["ok"], false);
assert_eq!(bad["error"]["category"], "invalid_arguments");
let unauth = tools_prepare_call(&json!({
"tool_id": "tool_bind",
"tools": allow,
"arguments": {"query": "x"}
}))
.unwrap();
assert_eq!(unauth["ok"], false);
assert_eq!(unauth["error"]["category"], "forbidden");
let good = tools_prepare_call(&json!({
"tool_id": "tool_find",
"tools": allow,
"arguments": {"query": "foo"},
"call_id": "c1"
}))
.unwrap();
assert_eq!(good["ok"], true);
assert_eq!(good["call"]["schema"], "ToolCallV1");
assert_eq!(good["call"]["tool_id"], "tool_find");
assert_eq!(good["needs_ledger"], false);
assert!(good["args_digest"].as_str().unwrap().starts_with("sha256-lite:"));
let allow2 = json!(["tool_bind"]);
let bind = tools_prepare_call(&json!({
"tool_id": "tool_bind",
"tools": allow2,
"arguments": {"query": "x"},
"call_id": "c2",
"logical_run_id": "run1",
"step_id": "s1"
}))
.unwrap();
assert_eq!(bind["ok"], true);
assert_eq!(bind["needs_ledger"], true);
assert_eq!(bind["spec"]["effect"], "execute");
assert!(bind["idempotency_key"]
.as_str()
.unwrap()
.starts_with("run1|s1|tool_bind|"));
}
#[test]
fn needs_ledger_only_for_mutating_effects() {
assert_eq!(
tools_needs_ledger(&json!({"effect": "read"})).unwrap()["needs_ledger"],
false
);
assert_eq!(
tools_needs_ledger(&json!({"effect": "write"})).unwrap()["needs_ledger"],
true
);
assert_eq!(
tools_needs_ledger(&json!({"effect": "execute"})).unwrap()["needs_ledger"],
true
);
}
#[test]
fn refuse_unsupported_schema_keywords() {
let err = tools_register(&json!({
"id": "bad",
"input_schema": {
"type": "object",
"oneOf": [{"type": "object"}]
}
}));
assert!(err.is_err());
}
}