diff --git a/crates/gateway/config-ui/ui/package.json b/crates/gateway/config-ui/ui/package.json
index 15b6fe5fc..3a59cd21b 100644
--- a/crates/gateway/config-ui/ui/package.json
+++ b/crates/gateway/config-ui/ui/package.json
@@ -11,6 +11,7 @@
"build": "node build.mjs",
"watch": "node build.mjs --watch",
"typecheck": "tsc --noEmit",
+ "pretest": "npm run build",
"test": "node --test \"src/**/*.test.mjs\""
},
"dependencies": {
diff --git a/crates/gateway/config-ui/ui/src/main.test.mjs b/crates/gateway/config-ui/ui/src/main.test.mjs
index ce11c3250..51694e8b4 100644
--- a/crates/gateway/config-ui/ui/src/main.test.mjs
+++ b/crates/gateway/config-ui/ui/src/main.test.mjs
@@ -2,8 +2,8 @@
// and asserts the live desk's first paint: standalone with no stored
// key, the auto-boot on #app must land on the key prompt - medallion,
// title, labeled password input, and submit button - without touching
-// the network. Run after `npm run build` (a debug `cargo build` also
-// produces dist/).
+// the network. Run with `npm test`, whose `pretest` script builds dist/
+// first.
import assert from "node:assert/strict";
import { readFile } from "node:fs/promises";
import path from "node:path";
diff --git a/crates/gateway/config-ui/ui/src/styles/tokens.test.mjs b/crates/gateway/config-ui/ui/src/styles/tokens.test.mjs
index f700108cb..0faec115a 100644
--- a/crates/gateway/config-ui/ui/src/styles/tokens.test.mjs
+++ b/crates/gateway/config-ui/ui/src/styles/tokens.test.mjs
@@ -3,8 +3,8 @@
// (shared-ui/tokens.css) and the cascade layer order, and
// dist/index.html must link that stylesheet - a dropped import in
// main.ts or a dropped would ship an unstyled UI without any
-// build failure. Run after `npm run build` (a debug `cargo build` also
-// produces dist/).
+// build failure. Run with `npm test`, whose `pretest` script builds
+// dist/ first.
import assert from "node:assert/strict";
import { readFile } from "node:fs/promises";
import path from "node:path";
diff --git a/crates/gateway/config-ui/ui/src/test-support.mjs b/crates/gateway/config-ui/ui/src/test-support.mjs
index 648f0503b..fb09fcfcb 100644
--- a/crates/gateway/config-ui/ui/src/test-support.mjs
+++ b/crates/gateway/config-ui/ui/src/test-support.mjs
@@ -16,7 +16,7 @@ const CONFIG_URL = "http://127.0.0.1:8081/config/";
let appModulePromise;
-/** Imports the built bundle once; run `npm run build` (or a debug `cargo build`) first. */
+/** Imports the built bundle once; `npm test` builds it first through the `pretest` script. */
export function loadApp() {
if (!appModulePromise) {
// Module evaluation touches `document` (the #app auto-boot probe),
diff --git a/crates/harness-internal/runner/src/host-run.rs b/crates/harness-internal/runner/src/host-run.rs
index 7f1115e36..4a9021684 100644
--- a/crates/harness-internal/runner/src/host-run.rs
+++ b/crates/harness-internal/runner/src/host-run.rs
@@ -18,7 +18,7 @@ use runvil::effect::ToolCallOrigin;
use runvil::packs::Prelude;
use runvil::tools::{ToolCatalog, ToolError, ToolErrorKind, ToolId, ToolInfo, ToolOutput};
use runvil::vfs::Access;
-use runvil::{MissingService, Prompt, Requirements, UnavailablePack};
+use runvil::{MissingService, Prompt, Requirements, UnavailablePack, UsablePack};
use runvil_plugin::{HostServices, Pack, PackId, PackInfo, ServiceId, ToolContext};
use serde_json::Value;
@@ -107,15 +107,21 @@ impl HostRunContext {
self.catalog.clone()
}
- /// The run's roster: the ids of its usable Packs, with or without
- /// tools, and an entry with the reason for each one that can't serve,
- /// both in id order.
- pub(crate) fn roster(&self) -> (Vec, Vec) {
+ /// The run's roster: each of its usable Packs, with or without tools,
+ /// with the vendor of its FQN, and an entry with the reason for each
+ /// one that can't serve, both in id order.
+ pub(crate) fn roster(&self) -> (Vec, Vec) {
let mut usable = Vec::new();
let mut unavailable = Vec::new();
for (name, pack) in &self.packs {
match pack {
- PackState::Usable { .. } => usable.push(name.clone()),
+ PackState::Usable { info, .. } => {
+ let vendor = info
+ .fqn
+ .split_once('/')
+ .map_or(info.fqn, |(vendor, _)| vendor);
+ usable.push(UsablePack::new(name.clone(), vendor));
+ }
PackState::Unavailable(reason) => {
unavailable.push(UnavailablePack::new(name.clone(), reason.clone()));
}
diff --git a/crates/harness-internal/runner/src/host-tests.rs b/crates/harness-internal/runner/src/host-tests.rs
index bdbdcefe4..b04f5da64 100644
--- a/crates/harness-internal/runner/src/host-tests.rs
+++ b/crates/harness-internal/runner/src/host-tests.rs
@@ -9,7 +9,7 @@ use std::sync::{Arc, Mutex};
use runvil::effect::{ToolCallOrigin, ToolCaller};
use runvil::vfs::{Origin, VfsRef};
-use runvil::{MissingService, Prompt, Requirements, UnavailablePack};
+use runvil::{MissingService, Prompt, Requirements, UnavailablePack, UsablePack};
use runvil_plugin::{
HostServices, Pack, PackFuture, PackId, PackInfo, PackRegistry, ServiceId, ServiceKey,
ToolContext, ToolError, ToolId, ToolInfo, ToolOutput,
@@ -191,7 +191,33 @@ fn catalog_ids(host: &HostContext, services: HostServices, prompt: &Prompt) -> V
fn usable(host: &HostContext, prompt: &Prompt) -> Vec {
let (run, _requirements) = begin(host, HostServices::new(), BTreeMap::new(), prompt);
let (usable, _unavailable) = run.roster();
- usable.iter().map(ToString::to_string).collect()
+ usable.iter().map(|entry| entry.pack.to_string()).collect()
+}
+
+#[test]
+fn the_roster_hands_each_usable_pack_with_the_vendor_the_run_picked() {
+ let host = host(&[
+ (info("runvil/kit"), offering(&["kit/a"])),
+ (info("acme/kit"), offering(&["kit/b"])),
+ (info("runvil/web"), offering(&["web/fetch"])),
+ (info("acme/poop"), Value::Null),
+ ]);
+ let (run, _requirements) = begin(
+ &host,
+ HostServices::new(),
+ BTreeMap::new(),
+ &prompt("uses:\n - acme/kit\n"),
+ );
+ let (usable, _unavailable) = run.roster();
+ assert_eq!(
+ usable,
+ [
+ UsablePack::new(name("kit"), "acme"),
+ UsablePack::new(name("subagents"), "runvil"),
+ UsablePack::new(name("web"), "runvil"),
+ ],
+ "the declared acme/kit reports acme, and every undeclared Pack reports runvil"
+ );
}
#[test]
@@ -328,7 +354,7 @@ fn the_roster_lists_the_builtin_stub_as_usable_and_each_pack_that_cannot_serve_w
let (usable, unavailable) = run.roster();
assert_eq!(
usable,
- [name("subagents")],
+ [UsablePack::new(name("subagents"), "runvil")],
"the undeclared stub with no tools is on the roster"
);
assert_eq!(
diff --git a/crates/harness-internal/runner/src/prepare.rs b/crates/harness-internal/runner/src/prepare.rs
index b91e6652b..f96c8074f 100644
--- a/crates/harness-internal/runner/src/prepare.rs
+++ b/crates/harness-internal/runner/src/prepare.rs
@@ -357,8 +357,8 @@ pub(crate) async fn prepare_noting_cancel(
})
}
-/// Sets `snapshot`'s catalog, roster, and declared preludes on `ctx`, then
-/// prepares it for `prompt`.
+/// Sets `snapshot`'s catalog, roster with each usable Pack's vendor, and
+/// declared preludes on `ctx`, then prepares it for `prompt`.
fn prepare_from_snapshot(
ctx: RunContext,
snapshot: &HostRunContext,
diff --git a/crates/harness-internal/runner/tests/it/prepare-ready.rs b/crates/harness-internal/runner/tests/it/prepare-ready.rs
index 224ae88fe..959b5b5cb 100644
--- a/crates/harness-internal/runner/tests/it/prepare-ready.rs
+++ b/crates/harness-internal/runner/tests/it/prepare-ready.rs
@@ -73,7 +73,10 @@ const DECLARES_SLOW: &str = "---\nname: declares-slow\ndescription: d\nrunvil: 0
/// A Pack-free prompt returning how many undeclared tools the run
/// offers.
const COUNTS_OFFERED: &str = "---\nname: counts\ndescription: d\nrunvil: 0\n---\n\n\
- # Title\n\n## Only\n\n```lua\nreturn #tools.extras() .. ' offered'\n```\n";
+ # Title\n\n## Only\n\n```lua\n\
+ local count = 0\n\
+ for _, pack in ipairs(tools.packs.extras()) do count = count + #pack.tools end\n\
+ return count .. ' offered'\n```\n";
/// A Pack whose tools wait on the test's [`Startup`].
struct Starting {
@@ -306,7 +309,7 @@ async fn an_undeclared_pack_whose_ready_fails_leaves_the_run_going_without_its_t
#[tokio::test]
async fn an_undeclared_pack_whose_ready_fails_raises_its_reason_when_the_prompt_offers_it() {
let offers_slow = "---\nname: offers-slow\ndescription: d\nrunvil: 0\n---\n\n\
- # Title\n\n## Only\n\n```lua\npacks.offer('slow')\nreturn 'offered'\n```\n";
+ # Title\n\n## Only\n\n```lua\ntools.offer('slow')\nreturn 'offered'\n```\n";
let (host, _moves, _startup) = slow_host(Phase::Failed("the fixture server is down"));
let outcome = drive_over(offers_slow, host).await;
let RunOutcome::Failed { message, .. } = &outcome else {
@@ -314,7 +317,7 @@ async fn an_undeclared_pack_whose_ready_fails_raises_its_reason_when_the_prompt_
};
assert!(
message.contains(
- "packs.offer: the slow Pack is unavailable in this run: \
+ "tools.offer: the slow Pack is unavailable in this run: \
the fixture server is down"
),
"the failure names the Pack and its ready failure: {message}"
@@ -344,8 +347,8 @@ async fn an_undeclared_third_party_pack_that_never_gets_ready_holds_no_run_up()
async fn an_undeclared_builtin_with_no_tools_has_an_object_the_prompt_can_offer() {
let reads_stub = "---\nname: reads-stub\ndescription: d\nrunvil: 0\n---\n\n\
# Title\n\n## Only\n\n```lua\n\
- local stub = packs.get('subagents')\n\
- packs.offer('subagents')\n\
+ local stub = tools.packs.get('subagents')\n\
+ tools.offer('subagents')\n\
return stub.name .. ':' .. #stub.tools\n```\n";
let host = HostContext::new(registry(&[]), HostServices::new());
assert_eq!(
diff --git a/crates/harness-internal/runner/tests/it/prepare.rs b/crates/harness-internal/runner/tests/it/prepare.rs
index 0e7467c3a..686319234 100644
--- a/crates/harness-internal/runner/tests/it/prepare.rs
+++ b/crates/harness-internal/runner/tests/it/prepare.rs
@@ -374,7 +374,7 @@ async fn an_undeclared_third_party_pack_is_not_in_the_run() {
let undeclared = "---\nname: undeclared\ndescription: d\nrunvil: 0\n---\n\n\
# Title\n\n## Only\n\n```lua\n\
local ok = pcall(tools.call, 'tools/echo', { value = 'hi' })\n\
- return tostring(ok) .. '|' .. tostring(packs.get('tools'))\n```\n";
+ return tostring(ok) .. '|' .. tostring(tools.packs.get('tools'))\n```\n";
assert_eq!(
completed(drive_over(undeclared, building(TOOLS)).await),
"false|nil",
@@ -402,19 +402,20 @@ async fn a_bare_entry_another_vendor_answers_is_refused_naming_its_fqn() {
}
#[tokio::test]
-async fn the_lists_split_the_offering_by_declared_pack_and_a_script_calls_a_tool_object() {
+async fn the_packs_split_by_declaration_and_a_script_calls_an_extras_tool_object() {
let offering = "---\nname: offering\ndescription: d\nrunvil: 0\n\
uses:\n - tests/tools\n---\n\n# Title\n\n## Only\n\n```lua\n\
- local required, extras = tools.required(), tools.extras()\n\
- local extra = extras[1]\n\
- return #required .. ':' .. required[1].id .. '|' .. #extras .. ':' .. extra.id .. '|' .. \
- tools.call(extra, { value = 'hi' })\n```\n";
+ local declared = tools.packs.get('tools')\n\
+ local extras = tools.packs.extras()\n\
+ local extra = extras[1].tools[1]\n\
+ return tostring(declared.required) .. ':' .. declared.tools[1].id .. '|' .. \
+ extras[1].name .. ':' .. extra.id .. '|' .. tools.call(extra, { value = 'hi' })\n```\n";
let extra = echo_pack("runvil/extra", None);
let host = HostContext::new(registry(&[TOOLS, extra]), HostServices::new());
assert_eq!(
completed(drive_over(offering, host).await),
- "1:tools/echo|1:extra/echo|hi",
- "the declared Pack's tool is required, the undeclared one's an extra, and its \
+ "true:tools/echo|extra:extra/echo|hi",
+ "the declared Pack is required, the undeclared one an extra, and its tool's \
object reaches its Pack"
);
}
diff --git a/crates/plugin-mcp/src/dynamic-tests.rs b/crates/plugin-mcp/src/dynamic-tests.rs
new file mode 100644
index 000000000..a736dd412
--- /dev/null
+++ b/crates/plugin-mcp/src/dynamic-tests.rs
@@ -0,0 +1,27 @@
+//! Tests for the Pack's two static tools.
+
+use std::collections::BTreeMap;
+
+use runvil_plugin::{Pack, PackId};
+use tokio::runtime::Handle;
+
+use super::Mcp;
+
+#[tokio::test]
+async fn only_the_listing_tool_describes_tools() {
+ let name = PackId::parse("mcp").expect("a valid Pack id");
+ let mcp = Mcp::new(&name, BTreeMap::new(), Handle::current())
+ .expect("the Pack names its tools under a valid Pack id");
+ let flags: Vec<(String, bool)> = mcp
+ .tools()
+ .iter()
+ .map(|tool| (tool.id.to_string(), tool.describes_tools))
+ .collect();
+ assert_eq!(
+ flags,
+ [
+ ("mcp/get_dynamic_tools".to_owned(), true),
+ ("mcp/call_dynamic_tool".to_owned(), false),
+ ]
+ );
+}
diff --git a/crates/plugin-mcp/src/dynamic.rs b/crates/plugin-mcp/src/dynamic.rs
index 51d59525f..a1f558639 100644
--- a/crates/plugin-mcp/src/dynamic.rs
+++ b/crates/plugin-mcp/src/dynamic.rs
@@ -7,7 +7,8 @@ use std::collections::BTreeMap;
use rmcp::model::JsonObject;
use rmcp::service::{Peer, RoleClient};
use runvil_plugin::{
- Pack, PackFuture, PackId, ToolContext, ToolError, ToolErrorKind, ToolId, ToolInfo, ToolOutput,
+ Pack, PackFuture, PackId, ToolCaller, ToolContext, ToolError, ToolErrorKind, ToolId, ToolInfo,
+ ToolOutput,
};
use serde_json::{Map, Value, json};
use tokio::runtime::Handle;
@@ -70,6 +71,16 @@ pub(crate) struct Mcp {
runtime: Handle,
}
+/// Marks `text` by who called: the section's own script receives it
+/// trusted, and every other caller, a model round included, untrusted,
+/// because the text comes from the servers.
+fn marked(caller: ToolCaller, text: String) -> ToolOutput {
+ match caller {
+ ToolCaller::Script => ToolOutput::trusted(text),
+ _ => ToolOutput::untrusted(text),
+ }
+}
+
fn invalid(text: impl Into) -> ToolError {
ToolError::message(text).with_kind(ToolErrorKind::InvalidArguments)
}
@@ -150,7 +161,8 @@ impl Mcp {
}
}
}),
- );
+ )
+ .describes_tools(true);
let call = ToolInfo::new(
id(CALL)?,
CALL_DESCRIPTION,
@@ -265,9 +277,9 @@ impl Mcp {
})
}
- /// Performs `call_dynamic_tool`. Every argument is checked before
- /// anything is sent.
- async fn call_tool(&self, args: Value) -> Result {
+ /// Performs `call_dynamic_tool` and returns the result's text. Every
+ /// argument is checked before anything is sent.
+ async fn call_tool(&self, args: Value) -> Result {
let mut members = members(
args,
"call_dynamic_tool takes a JSON object with the strings `namespace` and `toolName` \
@@ -303,13 +315,18 @@ impl Pack for Mcp {
) -> PackFuture<'a, Result> {
Box::pin(async move {
let tool = cx.tool();
+ let caller = cx.origin().caller;
if *tool == self.get.id {
- self.list(args).map(ToolOutput::untrusted)
+ self.list(args).map(|text| marked(caller, text))
} else if *tool == self.call.id {
- self.call_tool(args).await
+ self.call_tool(args).await.map(|text| marked(caller, text))
} else {
Err(ToolError::message(format!("MCP has no tool {tool}")))
}
})
}
}
+
+#[cfg(test)]
+#[path = "dynamic-tests.rs"]
+mod tests;
diff --git a/crates/plugin-mcp/src/lib.rs b/crates/plugin-mcp/src/lib.rs
index 8bf4ba4b6..36827b890 100644
--- a/crates/plugin-mcp/src/lib.rs
+++ b/crates/plugin-mcp/src/lib.rs
@@ -15,14 +15,20 @@
//! Cursor's `GetDynamicTools` and `CallDynamicTool`:
//!
//! - `get_dynamic_tools` takes the optional strings `namespace` and
-//! `toolName` and answers JSON text, which a script reads with
-//! `json.decode`. With no arguments it lists each server's namespace,
+//! `toolName` and answers JSON text. It describes tools, so a script's
+//! call receives the text as the servers wrote it and reads it with
+//! `json.decode`, while a model's call receives it in the untrusted
+//! envelope. With no arguments it lists each server's namespace,
//! status, and tool names, in name order; with `namespace`, that
//! server's tools with their input schemas; with both, one tool.
//! - `call_dynamic_tool` takes the strings `namespace` and `toolName` and
//! an optional object `arguments`, which defaults to `{}`, and calls that
//! server's tool.
//!
+//! Both tools answer a model round with untrusted text, and the section's
+//! own script with trusted text, so the script receives the server's text
+//! without the envelope.
+//!
//! A namespace is the server's name exactly as the configuration writes
//! it, and a tool's name is the one its server lists. Both must match
//! exactly. A server's status is `ready`, `loading` while it is still
@@ -79,8 +85,10 @@
//! - May depend on: `runvil-plugin`, `shared-*` crates, and outside
//! libraries. `cargo test -p build-xtask` enforces the Plugin family's
//! allow-list. Only [`install`] is public.
-//! - Every output is untrusted, because descriptions, schemas, and results
-//! all come from the servers.
+//! - Output to a model round is untrusted, because descriptions, schemas,
+//! and results all come from the servers, and output to the section's
+//! own script is trusted, so the script receives the server's text
+//! without the envelope.
//! - No reason, log line, `Debug` output, or error names an `env` or
//! `headers` value. They may name keys.
//! - It runs on the Host's runtime, read through the contract's
diff --git a/crates/plugin-mcp/src/result-tests.rs b/crates/plugin-mcp/src/result-tests.rs
index 4972a758b..5787c31ea 100644
--- a/crates/plugin-mcp/src/result-tests.rs
+++ b/crates/plugin-mcp/src/result-tests.rs
@@ -1,10 +1,10 @@
-//! Tests for how an MCP answer becomes tool output or a tool error.
+//! Tests for how an MCP answer becomes text or a tool error.
use std::time::Duration;
use rmcp::ServiceError;
use rmcp::model::{CallToolResult, ServerResult};
-use runvil_plugin::{OutputTrust, ToolErrorKind};
+use runvil_plugin::ToolErrorKind;
use serde_json::{Value, json};
use super::{output, render, service_error};
@@ -14,9 +14,7 @@ fn result(value: Value) -> CallToolResult {
}
fn text_of(value: Value) -> String {
- let output = render(&result(value)).expect("a success renders");
- assert_eq!(output.trust(), OutputTrust::Untrusted);
- output.text().to_owned()
+ render(&result(value)).expect("a success renders")
}
#[test]
@@ -83,7 +81,7 @@ fn content_blocks_win_over_structured_content() {
}
#[test]
-fn a_result_with_nothing_is_empty_untrusted_text() {
+fn a_result_with_nothing_is_empty_text() {
assert_eq!(text_of(json!({ "content": [] })), "");
}
@@ -165,8 +163,7 @@ fn a_failed_request_maps_through_output_and_a_good_one_renders() {
json!({ "content": [{ "type": "text", "text": "fine" }] }),
))))
.expect("renders");
- assert_eq!(good.text(), "fine");
- assert_eq!(good.trust(), OutputTrust::Untrusted);
+ assert_eq!(good, "fine");
}
#[test]
diff --git a/crates/plugin-mcp/src/result.rs b/crates/plugin-mcp/src/result.rs
index f1cc889a4..0eaae44c1 100644
--- a/crates/plugin-mcp/src/result.rs
+++ b/crates/plugin-mcp/src/result.rs
@@ -1,8 +1,8 @@
-//! Turns an MCP answer into tool output or a tool error.
+//! Turns an MCP answer into text or a tool error.
use rmcp::ServiceError;
use rmcp::model::{CallToolResult, ContentBlock, ResourceContents, ServerResult};
-use runvil_plugin::{ToolError, ToolErrorKind, ToolOutput};
+use runvil_plugin::{ToolError, ToolErrorKind};
/// What a content block this change does not know becomes. rmcp's content
/// types are `#[non_exhaustive]`, so a new kind reaches this text.
@@ -41,10 +41,8 @@ pub(crate) fn service_error(error: &ServiceError) -> ToolError {
ToolError::message(text).with_kind(kind)
}
-/// Maps the answer to a `tools/call` request.
-pub(crate) fn output(
- response: Result,
-) -> Result {
+/// Maps the answer to a `tools/call` request to its text.
+pub(crate) fn output(response: Result) -> Result {
match response.map_err(|e| service_error(&e))? {
ServerResult::CallToolResult(result) => render(&result),
_ => Err(ToolError::message(
@@ -56,7 +54,7 @@ pub(crate) fn output(
/// Joins a result's text. An `is_error` result becomes a backend error that
/// carries the server's text.
-pub(crate) fn render(result: &CallToolResult) -> Result {
+pub(crate) fn render(result: &CallToolResult) -> Result {
let text = text_of(result);
if result.is_error == Some(true) {
let message = if text.is_empty() {
@@ -66,7 +64,7 @@ pub(crate) fn render(result: &CallToolResult) -> Result {
};
return Err(ToolError::message(message).with_kind(ToolErrorKind::Backend));
}
- Ok(ToolOutput::untrusted(text))
+ Ok(text)
}
/// The text blocks, embedded text resources, and placeholders, joined with
diff --git a/crates/plugin-mcp/src/server.rs b/crates/plugin-mcp/src/server.rs
index f3b3a584b..9d3c0d9b2 100644
--- a/crates/plugin-mcp/src/server.rs
+++ b/crates/plugin-mcp/src/server.rs
@@ -8,7 +8,7 @@ use rmcp::model::{
RequestId, Tool,
};
use rmcp::service::{Peer, PeerRequestOptions, RoleClient};
-use runvil_plugin::{ToolError, ToolErrorKind, ToolOutput};
+use runvil_plugin::{ToolError, ToolErrorKind};
use serde_json::Value;
use tokio::runtime::Handle;
use tokio::sync::watch;
@@ -96,7 +96,7 @@ impl Drop for Server {
}
/// A spawned call, aborted when the call awaiting it is dropped.
-struct AbortOnDrop(JoinHandle>);
+struct AbortOnDrop(JoinHandle>);
impl Drop for AbortOnDrop {
fn drop(&mut self) {
@@ -125,14 +125,14 @@ impl Drop for CancelOnDrop {
}
}
-/// Sends one `tools/call` and renders the answer. It runs on the Host's
+/// Sends one `tools/call` and renders the answer as text. It runs on the Host's
/// runtime, so dropping the awaiting call aborts it and fires the guard.
async fn send(
peer: Peer,
name: String,
arguments: JsonObject,
runtime: Handle,
-) -> Result {
+) -> Result {
let request = ClientRequest::CallToolRequest(CallToolRequest::new(
CallToolRequestParams::new(name).with_arguments(arguments),
));
@@ -157,7 +157,7 @@ pub(crate) async fn call(
peer: Peer,
name: String,
arguments: JsonObject,
-) -> Result {
+) -> Result {
let mut task = AbortOnDrop(runtime.spawn(send(peer, name, arguments, runtime.clone())));
match (&mut task.0).await {
Ok(outcome) => outcome,
diff --git a/crates/plugin-mcp/tests/it/calls.rs b/crates/plugin-mcp/tests/it/calls.rs
index 14e09bdd3..8e0c1a7bb 100644
--- a/crates/plugin-mcp/tests/it/calls.rs
+++ b/crates/plugin-mcp/tests/it/calls.rs
@@ -5,11 +5,11 @@
use std::time::Duration;
use runvil_plugin::testing::TestCall;
-use runvil_plugin::{ToolErrorKind, ToolId};
+use runvil_plugin::{OutputTrust, ToolErrorKind, ToolId};
use serde_json::json;
use crate::fixture::Fixture;
-use crate::support::{Silent, call, invoke, pack_over, ready, remote, settled};
+use crate::support::{Silent, call, invoke, invoke_as_script, pack_over, ready, remote, settled};
#[tokio::test(flavor = "multi_thread")]
async fn a_call_sends_the_tools_own_name_and_returns_untrusted_text() {
@@ -23,6 +23,40 @@ async fn a_call_sends_the_tools_own_name_and_returns_untrusted_text() {
assert_eq!(text, r#"echo: {"q":"hello"}"#);
}
+#[tokio::test(flavor = "multi_thread")]
+async fn a_script_call_returns_the_servers_text_trusted_without_the_envelope() {
+ let fixture = Fixture::start().await;
+ let pack = pack_over(json!({ "GitHub": remote(&fixture, &json!({})) }));
+ ready(&pack, "GitHub").await;
+
+ let output = invoke_as_script(
+ &pack,
+ "call_dynamic_tool",
+ json!({ "namespace": "GitHub", "toolName": "Echo", "arguments": { "q": "hello" } }),
+ )
+ .await
+ .expect("succeeds");
+ assert_eq!(output.trust(), OutputTrust::Trusted);
+ assert_eq!(output.text(), r#"echo: {"q":"hello"}"#);
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn a_script_calls_is_error_result_is_the_same_backend_error_as_a_models() {
+ let fixture = Fixture::start().await;
+ let pack = pack_over(json!({ "GitHub": remote(&fixture, &json!({})) }));
+ ready(&pack, "GitHub").await;
+
+ let error = invoke_as_script(
+ &pack,
+ "call_dynamic_tool",
+ json!({ "namespace": "GitHub", "toolName": "fail", "arguments": {} }),
+ )
+ .await
+ .expect_err("isError fails");
+ assert_eq!(error.kind(), ToolErrorKind::Backend);
+ assert_eq!(error.to_string(), "it failed");
+}
+
#[tokio::test(flavor = "multi_thread")]
async fn a_call_without_arguments_sends_an_empty_object() {
let fixture = Fixture::start().await;
diff --git a/crates/plugin-mcp/tests/it/listing.rs b/crates/plugin-mcp/tests/it/listing.rs
index 3d04b01a5..a557a993a 100644
--- a/crates/plugin-mcp/tests/it/listing.rs
+++ b/crates/plugin-mcp/tests/it/listing.rs
@@ -3,11 +3,11 @@
use std::time::Duration;
-use runvil_plugin::ToolErrorKind;
+use runvil_plugin::{OutputTrust, ToolErrorKind};
use serde_json::{Value, json};
use crate::fixture::Fixture;
-use crate::support::{SECRET, Silent, invoke, list, pack_over, ready, remote};
+use crate::support::{SECRET, Silent, invoke, invoke_as_script, list, pack_over, ready, remote};
/// The fixture's tools as the listing with no arguments shows them.
fn named_tools() -> Value {
@@ -72,6 +72,20 @@ async fn the_listing_shows_each_server_by_its_own_name_with_the_tools_it_lists()
);
}
+#[tokio::test(flavor = "multi_thread")]
+async fn a_script_listing_is_trusted_json_equal_to_the_models() {
+ let fixture = Fixture::start().await;
+ let pack = pack_over(json!({ "GitHub": remote(&fixture, &json!({})) }));
+ ready(&pack, "GitHub").await;
+
+ let output = invoke_as_script(&pack, "get_dynamic_tools", Value::Null)
+ .await
+ .expect("the listing answers");
+ assert_eq!(output.trust(), OutputTrust::Trusted);
+ let listing: Value = serde_json::from_str(output.text()).expect("the listing is JSON");
+ assert_eq!(listing, list(&pack, json!({})).await);
+}
+
#[tokio::test(flavor = "multi_thread")]
async fn a_namespace_lists_its_tools_with_their_schemas_and_a_tool_name_lists_one() {
let fixture = Fixture::start().await;
diff --git a/crates/plugin-mcp/tests/it/support.rs b/crates/plugin-mcp/tests/it/support.rs
index 1ddca5b05..eab5c40ab 100644
--- a/crates/plugin-mcp/tests/it/support.rs
+++ b/crates/plugin-mcp/tests/it/support.rs
@@ -8,7 +8,7 @@ use std::time::Duration;
use runvil_plugin::testing::TestCall;
use runvil_plugin::{
HostServices, OutputTrust, Pack, PackId, PackInfo, PackRegistry, ServiceKey, TOKIO_RUNTIME,
- ToolError, ToolId,
+ ToolCaller, ToolError, ToolId, ToolOutput,
};
use serde_json::{Map, Value, json};
use tokio::net::TcpListener;
@@ -64,23 +64,37 @@ pub(crate) fn remote(fixture: &Fixture, headers: &Value) -> Value {
json!({ "url": fixture.url, "headers": headers })
}
-/// Calls the Pack's tool `mcp/` with `args` and returns its text,
-/// checking that the output is untrusted.
+fn tool_call(tool: &str) -> TestCall {
+ TestCall::new(ToolId::parse(&format!("mcp/{tool}")).expect("a tool id parses"))
+}
+
+/// Calls the Pack's tool `mcp/` with `args` from a model round and
+/// returns its text, checking that the output is untrusted.
pub(crate) async fn invoke(
pack: &Arc,
tool: &str,
args: Value,
) -> Result {
- let test = TestCall::new(ToolId::parse(&format!("mcp/{tool}")).expect("a tool id parses"));
+ let test = tool_call(tool).with_caller(ToolCaller::Model);
let output = pack.call(test.context(), args).await?;
assert_eq!(
output.trust(),
OutputTrust::Untrusted,
- "every output is untrusted"
+ "output to a model round is untrusted"
);
Ok(output.text().to_owned())
}
+/// Calls the Pack's tool `mcp/` with `args` from the section's own
+/// script and returns the whole output.
+pub(crate) async fn invoke_as_script(
+ pack: &Arc,
+ tool: &str,
+ args: Value,
+) -> Result {
+ pack.call(tool_call(tool).context(), args).await
+}
+
/// The JSON `get_dynamic_tools` answers for `args`.
pub(crate) async fn list(pack: &Arc, args: Value) -> Value {
let text = invoke(pack, "get_dynamic_tools", args)
diff --git a/crates/plugin-user-input/src/lib.rs b/crates/plugin-user-input/src/lib.rs
index 7519207ef..d934518cc 100644
--- a/crates/plugin-user-input/src/lib.rs
+++ b/crates/plugin-user-input/src/lib.rs
@@ -58,7 +58,7 @@
//! it.
//! - The model can ask the operator only when the prompt's Lua opts in.
//! A section offers the ask tool before its first loop round, with
-//! `packs.offer('user-input')` or by its id with
+//! the Pack, `tools.offer("user-input")`, or by its id with
//! `tools.offer("user-input/ask")`, and the model sees it as
//! `user-input_ask`. Neither inserting nor declaring the Pack
//! advertises anything to the model.
diff --git a/crates/runvil-internal/engine/src/error.rs b/crates/runvil-internal/engine/src/error.rs
index faf2e221d..a30d80e83 100644
--- a/crates/runvil-internal/engine/src/error.rs
+++ b/crates/runvil-internal/engine/src/error.rs
@@ -269,7 +269,7 @@ pub(crate) enum Error {
in_scope: Vec,
},
- /// A `tools.call` named no local tool and no tool in the run's catalog.
+ /// A `tools.call` named no adhoc tool and no tool in the run's catalog.
///
/// Script-initiated dispatch resolves a canonical id against the run's
/// whole catalog, not the section's advertised scope - the scope shapes
diff --git a/crates/runvil-internal/engine/src/execute.rs b/crates/runvil-internal/engine/src/execute.rs
index 8680ef2f8..66c8fb50d 100644
--- a/crates/runvil-internal/engine/src/execute.rs
+++ b/crates/runvil-internal/engine/src/execute.rs
@@ -59,7 +59,7 @@ pub use bindings::ModelBindings;
pub use config::{RunContext, RunLimits};
pub use error::{RunError, RunErrorKind, SourceLocation};
pub use requirements::{
- MissingService, RequirementCheck, Requirements, UnavailablePack, UnmetRequirement,
+ MissingService, RequirementCheck, Requirements, UnavailablePack, UnmetRequirement, UsablePack,
};
pub use run::{
AnswerRecord, ChatAnswerRecord, Effect, EffectAnswer, EffectId, EffectRecord, FailureRecord,
diff --git a/crates/runvil-internal/engine/src/execute/config.rs b/crates/runvil-internal/engine/src/execute/config.rs
index d1e13aa29..9392e7142 100644
--- a/crates/runvil-internal/engine/src/execute/config.rs
+++ b/crates/runvil-internal/engine/src/execute/config.rs
@@ -22,7 +22,7 @@ use crate::tools::ToolCatalog;
use super::bindings::ModelBindings;
use super::fill;
-use super::requirements::{Requirements, UnavailablePack};
+use super::requirements::{Requirements, UnavailablePack, UsablePack};
/// The inputs for one run of a prompt.
///
@@ -103,6 +103,10 @@ pub struct RunContext {
/// it can't. Set with [`packs`](RunContext::packs). Empty by
/// default.
pub(super) roster: BTreeMap>,
+ /// The vendor the caller reports for each Pack of the roster that
+ /// can serve, by name. Set with [`packs`](RunContext::packs). Empty
+ /// by default.
+ pub(super) vendors: BTreeMap,
/// The run's Pack preludes, in declaration order. Set with
/// [`preludes`](RunContext::preludes); every section VM installs each
/// one before `require`. Empty by default.
@@ -140,6 +144,7 @@ impl RunContext {
model_bindings: ModelBindings::default(),
tools: ToolCatalog::default(),
roster: BTreeMap::new(),
+ vendors: BTreeMap::new(),
preludes: Vec::new(),
}
}
@@ -260,19 +265,32 @@ impl RunContext {
}
/// Sets the run's roster: every installed Pack that can serve the run,
- /// declared by the prompt or not, and every one that can't, with the
- /// reason.
+ /// declared by the prompt or not, with its vendor, and every one that
+ /// can't, with the reason.
///
/// Each usable Pack gets an object in the run's Lua, with or without
/// tools. An unavailable one gets none, and offering it raises its
/// reason. A name in both lists counts as unavailable. Without a roster,
/// the run's Lua sees the declared Packs and the Packs with a tool
/// in the catalog.
+ ///
+ /// The caller reports each usable Pack's vendor, as it picked the
+ /// Pack. Every tool-call and tool-result event for a catalog tool of
+ /// that Pack records the vendor, and a run given no roster records
+ /// none.
#[must_use]
- pub fn packs(mut self, usable: Vec, unavailable: Vec) -> RunContext {
+ pub fn packs(
+ mut self,
+ usable: Vec,
+ unavailable: Vec,
+ ) -> RunContext {
+ self.vendors = usable
+ .iter()
+ .map(|entry| (entry.pack.clone(), entry.vendor.clone()))
+ .collect();
self.roster = usable
.into_iter()
- .map(|pack| (pack, None))
+ .map(|entry| (entry.pack, None))
.chain(
unavailable
.into_iter()
@@ -322,11 +340,18 @@ impl RunContext {
/// so `prepare` skips them. When the context's current model is
/// `None`, `prepare` skips the fill and the checks, and the model
/// bindings stay empty.
+ ///
+ /// `prepare` also sets [`Requirements::reserved_adhoc`] when a tool of
+ /// the catalog or a Pack of the roster, usable or not, has the Pack
+ /// id `adhoc`, which holds a section's own tools.
#[must_use]
pub fn prepare(mut self, prompt: &Prompt) -> (RunContext, Requirements) {
let mut requirements = Requirements::default();
self.model_bindings =
fill::fill_model_bindings(prompt, self.model.as_ref(), &mut requirements);
+ let adhoc = |pack: &PackId| pack.to_string() == "adhoc";
+ requirements.reserved_adhoc = self.tools.tools().iter().any(|tool| adhoc(&tool.id.pack()))
+ || self.roster.keys().any(adhoc);
(self, requirements)
}
@@ -415,6 +440,7 @@ impl fmt::Debug for RunContext {
.field("model_bindings", &self.model_bindings)
.field("tools", &self.tools)
.field("roster", &self.roster)
+ .field("vendors", &self.vendors)
.field(
"preludes",
&self.preludes.iter().map(Prelude::pack).collect::>(),
diff --git a/crates/runvil-internal/engine/src/execute/context-bound.rs b/crates/runvil-internal/engine/src/execute/context-bound.rs
index 965706840..3ffadf29c 100644
--- a/crates/runvil-internal/engine/src/execute/context-bound.rs
+++ b/crates/runvil-internal/engine/src/execute/context-bound.rs
@@ -16,9 +16,9 @@ use super::super::config::RunContext;
/// Builds the run's shared tool set: the frontmatter's declared Packs,
/// the `roster` moved out of the context, and every catalog tool the run
-/// can offer bound with the tool's info (its schema,
-/// description, and output kind), so run-time execution never consults the
-/// catalog again and never holds an implementation.
+/// can offer bound with the tool's info (its schema, description, output
+/// kind, and listing flag) and its Pack's vendor, so run-time execution
+/// never consults the catalog again and never holds an implementation.
pub(super) fn bound_tool_set(
prompt: &Prompt,
ctx: &RunContext,
@@ -51,12 +51,18 @@ fn offered_bindings(ctx: &RunContext) -> Vec {
tracing::warn!(tool = %tool.id, %name, %reason, "a tool is left out of the offering");
continue;
}
- offered.push(ToolBinding::from_info(&name, tool));
+ offered.push(catalog_binding(ctx, &name, tool));
taken.insert(name);
}
offered
}
+/// Binds `tool` under `alias`, stamped with the vendor the caller
+/// reported for its Pack, if any.
+fn catalog_binding(ctx: &RunContext, alias: &str, tool: &ToolInfo) -> ToolBinding {
+ ToolBinding::from_info(alias, tool).with_vendor(ctx.vendors.get(&tool.id.pack()).cloned())
+}
+
/// Why `tool` can't be offered under `name`: no model round could
/// advertise it, or an earlier offered tool has it. `None` when it can be
/// offered.
@@ -84,7 +90,7 @@ pub(super) fn catalog_bindings(ctx: &RunContext) -> BTreeMap PackId {
PackId::parse(text).expect("a static valid id")
}
+/// A prompt that declares no Pack and no model.
+fn declares_nothing() -> Prompt {
+ Prompt::parse(
+ "---\nname: t\ndescription: d\nrunvil: 0\n---\n\n# Run\n\n## Only\n\nDone.\n",
+ "requirements-test",
+ )
+ .0
+ .expect("the requirements test prompt parses")
+}
+
+fn context() -> RunContext {
+ RunContext::new("requirements-test", TEST_SEED, Timestamp::UNIX_EPOCH)
+}
+
+fn catalog(ids: &[&str]) -> ToolCatalog {
+ ToolCatalog::new(ids.iter().map(|tool| {
+ ToolInfo::new(
+ ToolId::parse(tool).expect("a static valid tool id"),
+ format!("{tool} tool"),
+ json!({ "type": "object" }),
+ )
+ }))
+ .expect("distinct ids make a valid catalog")
+}
+
+#[test]
+fn a_catalog_or_roster_naming_the_adhoc_pack_id_refuses_the_run_once() {
+ let contexts = [
+ (
+ "the catalog",
+ context().tools(catalog(&["web/fetch", "adhoc/grab"])),
+ ),
+ (
+ "the usable roster",
+ context().packs(vec![UsablePack::new(id("adhoc"), "acme")], Vec::new()),
+ ),
+ (
+ "the unavailable roster",
+ context().packs(
+ Vec::new(),
+ vec![UnavailablePack::new(id("adhoc"), "the server is down")],
+ ),
+ ),
+ ];
+ for (named_by, ctx) in contexts {
+ let (_, requirements) = ctx.prepare(&declares_nothing());
+ assert!(requirements.reserved_adhoc, "{named_by} names adhoc");
+ assert!(!requirements.is_satisfied(), "{named_by} names adhoc");
+ let refusal = requirements
+ .refusal()
+ .expect("a reserved Pack id refuses the run");
+ assert_eq!(
+ refusal.kind(),
+ RunErrorKind::RequirementsUnmet,
+ "{named_by}"
+ );
+ let notice = refusal.to_string();
+ assert_eq!(
+ notice.matches(RESERVED_ADHOC).count(),
+ 1,
+ "{named_by}: the notice names the reservation once: {notice}"
+ );
+ }
+}
+
+#[test]
+fn a_context_naming_no_adhoc_pack_leaves_the_reservation_clear() {
+ let ctx = context().tools(catalog(&["web/fetch"])).packs(
+ vec![UsablePack::new(id("web"), "runvil")],
+ vec![UnavailablePack::new(id("mcp"), "the server is down")],
+ );
+ let (_, requirements) = ctx.prepare(&declares_nothing());
+ assert!(!requirements.reserved_adhoc);
+ assert!(requirements.is_satisfied(), "{requirements:?}");
+}
+
+#[test]
+fn merge_keeps_a_set_reservation_from_either_side() {
+ let reserved = || Requirements {
+ reserved_adhoc: true,
+ ..Requirements::default()
+ };
+ let mut kept = reserved();
+ kept.merge(Requirements::default());
+ assert!(kept.reserved_adhoc, "merging a clear report keeps the flag");
+ let mut gained = Requirements::default();
+ gained.merge(reserved());
+ assert!(gained.reserved_adhoc, "merging a set report sets the flag");
+ assert_eq!(
+ gained.notice(),
+ format!("the environment cannot satisfy this prompt:\n{RESERVED_ADHOC}")
+ );
+}
+
fn web_down() -> UnavailablePack {
UnavailablePack::new(id("web"), "the search provider is missing")
}
diff --git a/crates/runvil-internal/engine/src/execute/requirements.rs b/crates/runvil-internal/engine/src/execute/requirements.rs
index 4df53ec85..83c79d30e 100644
--- a/crates/runvil-internal/engine/src/execute/requirements.rs
+++ b/crates/runvil-internal/engine/src/execute/requirements.rs
@@ -39,26 +39,35 @@ pub struct Requirements {
///
/// The caller adds these. The run fails until the Pack can serve.
pub unavailable: Vec,
+ /// Whether the run's tool catalog or Pack roster names the Pack id
+ /// `adhoc`, which holds a section's own tools.
+ ///
+ /// [`RunContext::prepare`](super::RunContext::prepare) sets it. The run
+ /// fails while it is set.
+ pub reserved_adhoc: bool,
}
impl Requirements {
/// Returns whether the report lets the run proceed.
///
- /// That holds when every model requirement is met and every required
- /// Pack is present, can serve, and has the services it needs.
+ /// That holds when every model requirement is met, every required
+ /// Pack is present, can serve, and has the services it needs, and no
+ /// Pack takes the Pack id `adhoc`.
#[must_use]
pub fn is_satisfied(&self) -> bool {
self.unmet_requirements.is_empty()
&& self.missing_required.is_empty()
&& self.missing_services.is_empty()
&& self.unavailable.is_empty()
+ && !self.reserved_adhoc
}
/// Adds the entries of `other` to this report.
///
/// Use it to combine the caller's Pack report with the report
/// from `RunContext::prepare`, so that one refusal names every gap.
- /// The merge skips an entry the report already holds.
+ /// The merge skips an entry the report already holds, and keeps
+ /// `reserved_adhoc` set when either report sets it.
///
/// The merge drops the `missing_required` entry of a Pack that
/// lacks a service or is unavailable: the service or unavailable entry
@@ -67,6 +76,7 @@ impl Requirements {
push_new(&mut self.missing_required, other.missing_required);
push_new(&mut self.missing_services, other.missing_services);
push_new(&mut self.unavailable, other.unavailable);
+ self.reserved_adhoc |= other.reserved_adhoc;
let (services, unavailable) = (&self.missing_services, &self.unavailable);
self.missing_required.retain(|id| {
!services.iter().any(|missing| missing.pack == *id)
@@ -120,6 +130,12 @@ impl Requirements {
entry.pack, entry.reason
);
}
+ if self.reserved_adhoc {
+ notice.push_str(
+ "\n- the run's tool catalog or Pack roster names the Pack id adhoc, \
+ which holds a section's own tools",
+ );
+ }
for unmet in &self.unmet_requirements {
let _ = match unmet.check {
RequirementCheck::ContextMinimum => write!(
@@ -149,6 +165,36 @@ fn push_new(entries: &mut Vec, incoming: Vec) {
}
}
+/// An installed Pack that can serve the run, and its vendor.
+///
+/// The run's roster, set with
+/// [`RunContext::packs`](super::RunContext::packs), lists every one the
+/// run holds. The caller reports each Pack's vendor as it picked the
+/// Pack, and every tool-call and tool-result event for one of the Pack's
+/// tools records it.
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[non_exhaustive]
+pub struct UsablePack {
+ /// The installed Pack.
+ pub pack: PackId,
+ /// The vendor the caller picked the Pack from, such as `runvil` or
+ /// `acme`.
+ pub vendor: String,
+}
+
+impl UsablePack {
+ /// Creates an entry stating that `pack`, from `vendor`, can serve.
+ ///
+ /// Only the caller builds these, for its roster.
+ #[must_use]
+ pub fn new(pack: PackId, vendor: impl Into) -> UsablePack {
+ UsablePack {
+ pack,
+ vendor: vendor.into(),
+ }
+ }
+}
+
/// An installed Pack that cannot serve the run, and why.
///
/// The caller's Pack report lists each one the prompt declares, and the
diff --git a/crates/runvil-internal/engine/src/execute/scheduler/apply.rs b/crates/runvil-internal/engine/src/execute/scheduler/apply.rs
index ea1db6b1a..651a40111 100644
--- a/crates/runvil-internal/engine/src/execute/scheduler/apply.rs
+++ b/crates/runvil-internal/engine/src/execute/scheduler/apply.rs
@@ -184,15 +184,16 @@ impl Scheduler {
/// `ToolResult` report - under the model's call id when the model
/// issued the call (a tool's own failure then resumes as untrusted
/// failure text), else as a script call classified by the binding's
- /// declared output kind. The counts were taken at dispatch, so the
- /// body is handed `None` for them.
+ /// declared output kind. A script call that receives a listing marks
+ /// the chain's frame's innermost open adhoc call. The counts were
+ /// taken at dispatch, so the body is handed `None` for them.
fn accept_tool_call(
- &self,
+ &mut self,
chain: ChainIndex,
call: &ToolCallContinuation,
result: std::result::Result,
) -> Result {
- let chain = &self.chains[chain.index()];
+ let chain = &mut self.chains[chain.index()];
// The shared dispatch body reports through this chain's emitter, so
// its reports land in the buffer under this chain's task.
let emitter = chain.ctx.emitter();
@@ -228,12 +229,17 @@ impl Scheduler {
section,
Some(call.report),
) {
- Ok(outcome) => ToolCallOutcome::from_dispatch(
- call.binding.output_kind(),
- call.binding.alias(),
- outcome.into_content(),
- )
- .map_err(Error::from),
+ Ok(outcome) => {
+ if outcome.listing() {
+ chain.frame_mut()?.mark_listing();
+ }
+ ToolCallOutcome::from_dispatch(
+ call.binding.output_kind(),
+ call.binding.alias(),
+ outcome.into_content(),
+ )
+ .map_err(Error::from)
+ }
Err(error) => Err(Error::from(error)),
},
}
diff --git a/crates/runvil-internal/engine/src/execute/scheduler/chain_record.rs b/crates/runvil-internal/engine/src/execute/scheduler/chain_record.rs
index e8a09f5f0..e1fdaadc5 100644
--- a/crates/runvil-internal/engine/src/execute/scheduler/chain_record.rs
+++ b/crates/runvil-internal/engine/src/execute/scheduler/chain_record.rs
@@ -11,7 +11,6 @@ use std::sync::Arc;
use mlua::Thread;
use runvil_types::ids::{ChainId, TaskId};
use runvil_types::metrics::Usage;
-use runvil_types::tools::ToolId;
use runvil_vfs::Access;
use crate::error::DepthVia;
@@ -19,7 +18,7 @@ use crate::execute::context::RunState;
use crate::execute::protocol::{Answer, Blocked};
use crate::execute::section_context::{SectionContext, TaskSeed};
use crate::execute::walk_target::SlicePath;
-use crate::lua::UsageAnchor;
+use crate::lua::{Advertised, UsageAnchor};
use crate::model::{Message, ModelId};
use crate::parser::{Block, BodyText, Prompt, Section};
use crate::{Error, Result};
@@ -267,12 +266,13 @@ pub(super) struct Chain {
/// `tasks.concurrency` lowers it, clamped to the parent's.
pub(super) concurrency: NonZeroUsize,
/// The tool scope the chain's last `chat` round advertised, keyed by
- /// alias, each name's catalog tool or `None` for a local tool: a copy
- /// of the section's rendered tool list's map. The round's answer is
- /// checked against it, so a tool name the model invents or reaches for
- /// outside the scope fails as out of scope. `None` before the chain's
- /// first round.
- pub(super) advertised: Option>>,
+ /// wire name, each name's tool id and vendor: a copy of the section's
+ /// rendered tool list's map. The round's answer is checked against it,
+ /// so a tool name the model invents or reaches for outside the scope
+ /// fails as out of scope, and each requested call's event is stamped
+ /// from it. It never routes a call. `None` before the chain's first
+ /// round.
+ pub(super) advertised: Option>,
/// The provider's token counts for the chain's `chat` rounds, which the
/// next round's context precheck counts from.
pub(super) anchor: ChatAnchor,
diff --git a/crates/runvil-internal/engine/src/execute/scheduler/chat.rs b/crates/runvil-internal/engine/src/execute/scheduler/chat.rs
index e73d25ec1..24e22026f 100644
--- a/crates/runvil-internal/engine/src/execute/scheduler/chat.rs
+++ b/crates/runvil-internal/engine/src/execute/scheduler/chat.rs
@@ -2,8 +2,8 @@
//! section VM.
//!
//! Dispatch first refuses an empty list. It then resolves the round's
-//! binding and the section's rendered tool list - built from the bound
-//! and local halves and attached to the list by the first round to reach
+//! binding and the section's rendered tool list - built from the
+//! section's offers and attached to the list by the first round to reach
//! the build, then reused by every later round - copies the list's dispatch
//! map onto the chain as `advertised`, prechecks the projected
//! conversation, with room kept for the reply, against the model's
@@ -29,15 +29,14 @@ use runvil_types::emitter::Emitter;
use runvil_types::event::{ReplyOrigin, lifecycle};
use runvil_types::ids::RoundId;
use runvil_types::metrics::ToolCallEvent;
-use runvil_types::tools::ToolId;
use crate::execute::protocol::{Answer, ChatOutcome, ChatResult};
use crate::execute::run::Effect;
use crate::execute::scope::prepare_effective_scope;
use crate::execute::turn::{Served, advance_turn, report_model_turn};
use crate::lua::{
- MessageList, OverflowReason, current_tool_bindings, output_reserve, precheck, project_messages,
- resolve_model_binding,
+ Advertised, MessageList, OverflowReason, current_dynamic_tools, current_tool_bindings,
+ output_reserve, precheck, project_messages, resolve_model_binding,
};
use crate::model::{Completion, CompletionErrorKind, CompletionResult, ModelBinding, ToolCall};
use crate::{Error, Result};
@@ -123,15 +122,16 @@ impl Scheduler {
};
let handles = frame.reporting_handles();
let emitter = handles.emitter;
- // The section's first round renders the effective bindings plus
- // every local Lua tool, and every offer raises after that, so each
+ // The section's first round renders its static offers and records
+ // its dynamic ones, and every offer raises after that, so each
// later round sends the same list.
let rendered = if let Some(rendered) = list.rendered_tools() {
rendered
} else {
- let bound = current_tool_bindings(chain.ctx.tool_set(), vm.tool_runtime())?;
- let locals = vm.local_tool_schemas()?;
- let rendered = prepare_effective_scope(&bound, &locals, emitter.as_ref(), §ion)?;
+ let (set, runtime, adhoc) = (chain.ctx.tool_set(), vm.tool_runtime(), vm.adhoc_tools());
+ let bound = current_tool_bindings(set, runtime, adhoc)?;
+ let mut rendered = prepare_effective_scope(&bound, emitter.as_ref(), §ion)?;
+ rendered.dynamic = current_dynamic_tools(set, runtime, adhoc, &bound)?;
list.attach_rendered_tools(rendered.clone());
rendered
};
@@ -338,14 +338,19 @@ impl ArrivedRound {
served: &Served,
turn: u32,
calls: &[ToolCall],
- advertised: &BTreeMap>,
+ advertised: &BTreeMap,
global_exists: impl Fn(&str) -> bool,
) -> Result {
let events: Vec = calls
.iter()
.map(|call| {
+ let (tool, vendor) = match advertised.get(call.name()).cloned() {
+ Some(Advertised { id, vendor }) => (Some(id), vendor),
+ None => (None, None),
+ };
ToolCallEvent::new(call.id(), call.name(), tool_call_arguments(call).clone())
- .with_tool(advertised.get(call.name()).cloned().flatten())
+ .with_tool(tool)
+ .with_vendor(vendor)
})
.collect();
self.emitter
diff --git a/crates/runvil-internal/engine/src/execute/scheduler/dispatch.rs b/crates/runvil-internal/engine/src/execute/scheduler/dispatch.rs
index bea112ad7..26ed0df93 100644
--- a/crates/runvil-internal/engine/src/execute/scheduler/dispatch.rs
+++ b/crates/runvil-internal/engine/src/execute/scheduler/dispatch.rs
@@ -5,7 +5,7 @@
//! lands. Every store operation is a leaf yield, handed to the caller
//! uniformly for all backends - no inline fast path - so interleaving
//! behavior never depends on which backend serves the mount.
-//! The `tool_call`, `tool_calls`, `local_tool_done`, `chat`, `spawn`,
+//! The `tool_call`, `tool_calls`, `adhoc_tool_done`, `chat`, `spawn`,
//! `timer`, and task wait, inspection, note, concurrency, and cancel arms
//! are defined in their own modules.
@@ -93,7 +93,7 @@ fn blocked_on(request: &Request) -> Option {
| Request::Concurrency { .. }
| Request::Note { .. }
| Request::Cancel { .. }
- | Request::LocalToolDone { .. } => None,
+ | Request::AdhocToolDone { .. } => None,
}
}
@@ -119,7 +119,7 @@ impl Scheduler {
///
/// # Errors
/// Returns the store arm's error when the chain's access capability is
- /// gone, or the `local_tool_done` arm's error when no local tool call is
+ /// gone, or the `adhoc_tool_done` arm's error when no adhoc tool call is
/// open.
pub(super) fn dispatch(&mut self, id: ChainIndex, request: Request) -> Result<()> {
self.chains[id.index()].blocked = blocked_on(&request);
@@ -195,7 +195,7 @@ impl Scheduler {
self.dispatch_tool_calls(id, calls, turn);
Ok(())
}
- Request::LocalToolDone { outcome } => self.dispatch_local_tool_done(id, outcome),
+ Request::AdhocToolDone { outcome } => self.dispatch_adhoc_tool_done(id, outcome),
Request::Store { op } => self.dispatch_vfs(id, op),
Request::Chat { list, binding } => {
self.dispatch_chat(id, &list, binding);
diff --git a/crates/runvil-internal/engine/src/execute/scheduler/test_hooks.rs b/crates/runvil-internal/engine/src/execute/scheduler/test_hooks.rs
index 1f4281b79..941ac2b24 100644
--- a/crates/runvil-internal/engine/src/execute/scheduler/test_hooks.rs
+++ b/crates/runvil-internal/engine/src/execute/scheduler/test_hooks.rs
@@ -12,7 +12,7 @@ use runvil_types::tools::ToolId;
use crate::Result;
use crate::execute::walk_target::SlicePath;
-use crate::lua::ToolSet;
+use crate::lua::{Advertised, ToolSet};
use super::chain::ChainStart;
use super::chain_record::{Admission, CallDepth, ChainKind, SectionIndex};
@@ -62,7 +62,13 @@ impl Scheduler {
.advertised
.as_mut()
.expect("the chain advertised a round")
- .insert(name.to_owned(), Some(tool));
+ .insert(
+ name.to_owned(),
+ Advertised {
+ id: tool,
+ vendor: None,
+ },
+ );
}
/// The state of one task's slot, or `None` when no task with that id
diff --git a/crates/runvil-internal/engine/src/execute/scheduler/tool_call-adhoc.rs b/crates/runvil-internal/engine/src/execute/scheduler/tool_call-adhoc.rs
new file mode 100644
index 000000000..dba3159f0
--- /dev/null
+++ b/crates/runvil-internal/engine/src/execute/scheduler/tool_call-adhoc.rs
@@ -0,0 +1,113 @@
+//! The adhoc arm of the `tool_call` arm: a call routed to an adhoc tool,
+//! answered with its handler, and the `adhoc_tool_done` request that
+//! closes it.
+
+use std::sync::Arc;
+
+use runvil_types::event::lifecycle;
+use runvil_types::tools::OutputTrust;
+
+use crate::execute::protocol::{AdhocToolOutcome, Answer, ToolCallOutcome};
+use crate::execute::section_context::AdhocCall;
+use crate::lua::{ScriptReport, ToolBinding};
+use crate::{Error, Result};
+
+use super::super::{CallSite, ChainIndex, Scheduler};
+use super::ToolCallDispatch;
+
+impl Scheduler {
+ /// Answers a call routed to the adhoc tool `binding` binds: the
+ /// one-time counts install, the attempt counted under the tool's id,
+ /// the call opened on the frame, then the handler's answer.
+ pub(super) fn prepare_adhoc_call(
+ &mut self,
+ id: ChainIndex,
+ binding: &ToolBinding,
+ args: serde_json::Value,
+ site: &CallSite,
+ ) -> Result {
+ let report = ScriptReport {
+ turn: self.call_turn(id, site),
+ };
+ let counts = self.section_call_counts(id)?;
+ // The attempt counts at dispatch, before the handler runs, so a
+ // handler that then fails still counts.
+ let counted = binding.id().to_string();
+ counts.ensure(&counted)?;
+ counts.increment(&counted)?;
+ self.chains[id.index()]
+ .frame_mut()?
+ .push_adhoc_call(AdhocCall {
+ tool: binding.id().clone(),
+ alias: binding.alias().to_owned(),
+ call_id: site.call_id().map(str::to_owned),
+ report,
+ listing: false,
+ });
+ Ok(ToolCallDispatch::Answered(Answer::ToolCallResult(Ok(
+ ToolCallOutcome::Adhoc {
+ alias: binding.alias().to_owned(),
+ args,
+ },
+ ))))
+ }
+
+ /// Dispatches an `adhoc_tool_done` request: closes the chain's
+ /// innermost open adhoc tool call and answers it. A returned text
+ /// reports `TOOL_CALL_SUCCEEDED` and a trusted `ToolResult` - the
+ /// prompt author wrote the handler, so its output passes verbatim -
+ /// under the tool's id, no vendor, the call id (or none for a script
+ /// call), and the turn recorded at dispatch, then resumes as the text.
+ /// A call marked as having fetched a listing while it was open instead
+ /// returns its text wrapped with the run's nonce and reports it
+ /// untrusted. A rejected return reports `TOOL_CALL_FAILED` and resumes
+ /// as its error. A raise reports `TOOL_CALL_FAILED` and resumes empty:
+ /// the shim raises the handler's own value in its place.
+ ///
+ /// # Errors
+ /// Returns [`Error::Internal`] when the chain has no frame or no open
+ /// adhoc call, which only a shim bug produces.
+ pub(in crate::execute::scheduler) fn dispatch_adhoc_tool_done(
+ &mut self,
+ id: ChainIndex,
+ outcome: AdhocToolOutcome,
+ ) -> Result<()> {
+ let chain = &mut self.chains[id.index()];
+ let emitter = Arc::clone(chain.ctx.emitter());
+ let section = chain.section_name().to_owned();
+ let call = chain.frame_mut()?.pop_adhoc_call().ok_or(Error::internal(
+ "an adhoc tool's completion closes the call that opened it",
+ ))?;
+ let answer = match outcome {
+ AdhocToolOutcome::Returned(text) => {
+ emitter.report(§ion, lifecycle::TOOL_CALL_SUCCEEDED);
+ let (text, trust) = if call.listing {
+ (chain.ctx.nonce().wrap(&text), OutputTrust::Untrusted)
+ } else {
+ (text, OutputTrust::Trusted)
+ };
+ emitter.tool_result(
+ §ion,
+ call.report.turn,
+ call.call_id.as_deref().unwrap_or(""),
+ &call.alias,
+ Some(&call.tool),
+ None,
+ &text,
+ trust,
+ );
+ Ok(ToolCallOutcome::Plain(text))
+ }
+ AdhocToolOutcome::BadReturn(error) => {
+ emitter.report(§ion, lifecycle::TOOL_CALL_FAILED);
+ Err(Error::from(error))
+ }
+ AdhocToolOutcome::Raised => {
+ emitter.report(§ion, lifecycle::TOOL_CALL_FAILED);
+ Ok(ToolCallOutcome::Plain(String::new()))
+ }
+ };
+ self.answer_inline(id, Answer::ToolCallResult(answer));
+ Ok(())
+ }
+}
diff --git a/crates/runvil-internal/engine/src/execute/scheduler/tool_call.rs b/crates/runvil-internal/engine/src/execute/scheduler/tool_call.rs
index a98737972..4d82dc5b7 100644
--- a/crates/runvil-internal/engine/src/execute/scheduler/tool_call.rs
+++ b/crates/runvil-internal/engine/src/execute/scheduler/tool_call.rs
@@ -1,16 +1,18 @@
//! The `tool_call` arm: one dispatched tool call yielded by a section VM,
//! script-initiated (`tools.call`) or model-issued (the loop shim, with the
-//! model's `call_id`), plus the `local_tool_done` arm that closes a local
+//! model's `call_id`), plus the `adhoc_tool_done` arm that closes an adhoc
//! tool call.
//!
//! Each call's route is decided once, by `tool_route`, on the driver thread
-//! before any leaf work. A local Lua tool is answered with its handler;
-//! anything else is a catalog tool, which resolves against the run's
-//! offering (a model call by wire name, a script call by canonical id,
-//! which also reaches a catalog tool left out of the offering), has its
-//! attempt counted, and is issued as a `ToolCall` effect, carrying an
-//! identity forked from the chain's access, whose answer the driver applies
-//! through the shared dispatch body. The call's `CallSite` names who asked.
+//! before any leaf work, from the call's `CallSite`, which names who
+//! asked. A model call's wire name routes by the entry the current frame's
+//! section's rendered list holds for it, and a script call routes by id.
+//! An adhoc tool is answered with its handler; anything else is a catalog
+//! tool, which resolves against the run's offering (a model call by wire
+//! name, a script call by id, which also reaches a catalog tool left out
+//! of the offering), has its attempt counted, and is issued as a
+//! `ToolCall` effect, carrying an identity forked from the chain's access,
+//! whose answer the driver applies through the shared dispatch body.
//! A model-issued call, alone or batched, always resumes a bound tool with
//! content - a tool's own failure becomes untrusted failure text - and
//! `ToolResult` fires under the id and the turn of the round that requested
@@ -20,7 +22,7 @@
//! The loop sends a round's unanswered calls together as one
//! `tool_calls` request. The arm walks them in the model's order and
//! issues each catalog call at once into a slot of the chain's batch,
-//! stopping at the first call whose route is a local tool. A call that
+//! stopping at the first call whose route is an adhoc tool. A call that
//! fails to route or to prepare fills its slot with the error and stops
//! the batch too. Each landed answer fills its call's slot, and the
//! chain is answered once no slot is open: every text in call order, or
@@ -29,34 +31,37 @@
//! an ordinary `tool_call`. The calls in flight run concurrently, each
//! under its own forked identity.
//!
-//! A local tool call is a two-yield handshake. The `tool_call` answer is
-//! [`ToolCallOutcome::Local`], which hands the shim the handler, and the
-//! frame opens a [`LocalCall`] for it. The shim runs the handler inside the
+//! An adhoc tool call is a two-yield handshake. The `tool_call` answer is
+//! [`ToolCallOutcome::Adhoc`], which hands the shim the handler, and the
+//! frame opens an [`AdhocCall`](crate::execute::section_context::AdhocCall)
+//! for it. The shim runs the handler inside the
//! chain's block coroutine, so the handler's own suspending calls are
-//! ordinary requests of this chain, then yields `local_tool_done`. That
+//! ordinary requests of this chain, then yields `adhoc_tool_done`. That
//! arm closes the innermost open call and reports it: the succeeded or
-//! failed observation and, on success, the trusted `ToolResult` under the
-//! call id recorded at dispatch. A local call never issues leaf work of
-//! its own.
+//! failed observation and, on success, the `ToolResult` under the tool's
+//! id and the call id recorded at dispatch, trusted unless the handler
+//! fetched a listing while the call was open. An adhoc call never issues
+//! leaf work of its own. The adhoc arm sits in the `adhoc` child.
+
+#[path = "tool_call-adhoc.rs"]
+mod adhoc;
use std::sync::Arc;
use std::sync::atomic::Ordering;
-use runvil_types::event::lifecycle;
-use runvil_types::tools::{OutputTrust, ToolId};
+use runvil_types::tools::ToolId;
use runvil_vfs::detail;
-use crate::execute::protocol::{Answer, LocalToolOutcome, ToolCallOutcome, ToolCallRecord};
+use crate::execute::protocol::{Answer, ToolCallOutcome, ToolCallRecord};
use crate::execute::run::{Effect, ToolCallOrigin, ToolCaller};
-use crate::execute::section_context::LocalCall;
-use crate::lua::{ScriptReport, ToolCallCounts, current_tool_bindings};
+use crate::lua::{ScriptReport, ToolBinding, ToolCallCounts, current_tool_bindings};
use crate::{Error, Result};
use super::dispatch::unbound_tool_call;
use super::{CallSite, ChainIndex, Continuation, Scheduler, ToolCallContinuation, prompt_origin};
/// How one `tool_call` dispatch resolved: a bound call issued as an effect
-/// and parked on the pending table, or a local Lua tool's answer settled
+/// and parked on the pending table, or an adhoc tool's answer settled
/// on the driver thread. A preparation failure returns `Err` instead.
#[derive(Debug)]
pub(super) enum ToolCallDispatch {
@@ -68,9 +73,9 @@ pub(super) enum ToolCallDispatch {
/// a lone call and a batched one route alike.
#[derive(Debug)]
enum ToolRoute {
- /// A local Lua tool of the chain's section VM, answered with its
+ /// An adhoc tool of the chain's section VM, answered with its
/// handler.
- Local,
+ Adhoc(ToolBinding),
/// A catalog tool, resolved against the run's offering and issued as
/// an effect.
Catalog,
@@ -78,7 +83,7 @@ enum ToolRoute {
impl Scheduler {
/// Dispatches a `tool_call` request. An issued bound call parks the
- /// chain in the pending table; a local Lua tool's handler resumes the
+ /// chain in the pending table; an adhoc tool's handler resumes the
/// chain on the spot; every preparation failure - an unbound alias,
/// the counts install - is the call's answer, resumed
/// into the caller so an author `pcall` catches it exactly as a tool
@@ -122,18 +127,16 @@ impl Scheduler {
) {
let mut batch = Vec::with_capacity(calls.len());
for (slot, call) in calls.into_iter().enumerate() {
- let issued = match self.tool_route(id, &call.name) {
- Ok(ToolRoute::Local) => break,
- Ok(ToolRoute::Catalog) => self.prepare_catalog_call(
- id,
- &call.name,
- call.arguments,
- CallSite::Batch {
- call_id: call.id,
- turn,
- slot,
- },
- ),
+ let site = CallSite::Batch {
+ call_id: call.id,
+ turn,
+ slot,
+ };
+ let issued = match self.tool_route(id, &call.name, &site) {
+ Ok(ToolRoute::Adhoc(_)) => break,
+ Ok(ToolRoute::Catalog) => {
+ self.prepare_catalog_call(id, &call.name, call.arguments, site)
+ }
Err(error) => Err(error),
};
match issued {
@@ -148,18 +151,29 @@ impl Scheduler {
self.answer_full_batch(id);
}
- /// Decides the route of the call named `alias`, the one decision a
- /// lone call and a batch share. A local tool of the chain's section VM
- /// wins over the catalog.
- fn tool_route(&self, id: ChainIndex, alias: &str) -> Result {
- if self.chains[id.index()]
- .frame()?
- .vm()?
- .has_local_tool(alias)?
- {
- return Ok(ToolRoute::Local);
- }
- Ok(ToolRoute::Catalog)
+ /// Decides the route of the call at `site` naming `name`, the one
+ /// decision a lone call and a batch share. A model call looks its wire
+ /// name up in the rendered list of the current frame's section, never
+ /// in the chain's advertised scope, which another section's rounds
+ /// overwrite while an adhoc tool's handler runs; with no rendered list
+ /// it routes as a catalog call. A script call routes by id. Either goes
+ /// to the adhoc tool the id names, when it is one.
+ fn tool_route(&self, id: ChainIndex, name: &str, site: &CallSite) -> Result {
+ let vm = self.chains[id.index()].frame()?.vm()?;
+ let target = if site.call_id().is_some() {
+ match vm.rendered_target(name) {
+ Some(advertised) => advertised.id.to_string(),
+ None => return Ok(ToolRoute::Catalog),
+ }
+ } else {
+ name.to_owned()
+ };
+ let adhoc = if target.contains('/') {
+ vm.adhoc_tools().binding(&target)?
+ } else {
+ None
+ };
+ Ok(adhoc.map_or(ToolRoute::Catalog, ToolRoute::Adhoc))
}
/// The turn every report of a call at `site` carries: the requesting
@@ -171,13 +185,22 @@ impl Scheduler {
}
/// The chain's section's tool-call counts, which the section's first
- /// call installs.
+ /// call installs, seeded from its rendered list once there is one and
+ /// from its live scope before.
fn section_call_counts(&mut self, id: ChainIndex) -> Result {
let chain = &mut self.chains[id.index()];
- let effective =
- current_tool_bindings(chain.ctx.tool_set(), chain.frame()?.vm()?.tool_runtime())?;
+ let vm = chain.frame()?.vm()?;
+ let ids = match vm.rendered_ids() {
+ Some(ids) => ids,
+ None => {
+ current_tool_bindings(chain.ctx.tool_set(), vm.tool_runtime(), vm.adhoc_tools())?
+ .iter()
+ .map(|binding| binding.id().clone())
+ .collect()
+ }
+ };
let ctx = chain.ctx.clone();
- chain.frame_mut()?.script_call_counts(&ctx, &effective)
+ chain.frame_mut()?.script_call_counts(&ctx, &ids)
}
/// Fills `slot` of the batch the chain is parked on with a landed
@@ -199,7 +222,7 @@ impl Scheduler {
Answer::ToolCallResult(Ok(ToolCallOutcome::Plain(text))) => Ok(text),
Answer::ToolCallResult(Err(error)) => Err(error),
Answer::ToolCallResult(Ok(
- ToolCallOutcome::Structured(_) | ToolCallOutcome::Local { .. },
+ ToolCallOutcome::Structured(_) | ToolCallOutcome::Adhoc { .. },
))
| Answer::Infer(_)
| Answer::Call(_)
@@ -244,13 +267,13 @@ impl Scheduler {
self.answer_inline(id, Answer::ToolCallsResult(answer));
}
- /// The fallible half of tool-call dispatch, by the call's route: a
- /// local tool (the one-time counts install, the attempt counted, then
+ /// The fallible half of tool-call dispatch, by the call's route: an
+ /// adhoc tool (the one-time counts install, the attempt counted, then
/// the handler's answer), or a catalog tool, which
/// `prepare_catalog_call` issues.
///
/// Every report the call makes carries the turn of the model round
- /// that requested it, so a local handler earlier in the same batch
+ /// that requested it, so an adhoc handler earlier in the same batch
/// that runs model rounds cannot shift it. A script call, or a
/// model-issued one yielded without a turn, reports the counter's
/// value at dispatch.
@@ -261,30 +284,8 @@ impl Scheduler {
args: serde_json::Value,
site: CallSite,
) -> Result {
- match self.tool_route(id, alias)? {
- ToolRoute::Local => {
- let report = ScriptReport {
- turn: self.call_turn(id, &site),
- };
- let counts = self.section_call_counts(id)?;
- // The attempt counts at dispatch, before the handler runs, so
- // a handler that then fails still counts.
- counts.ensure(alias)?;
- counts.increment(alias)?;
- self.chains[id.index()]
- .frame_mut()?
- .push_local_call(LocalCall {
- alias: alias.to_owned(),
- call_id: site.call_id().map(str::to_owned),
- report,
- });
- Ok(ToolCallDispatch::Answered(Answer::ToolCallResult(Ok(
- ToolCallOutcome::Local {
- alias: alias.to_owned(),
- args,
- },
- ))))
- }
+ match self.tool_route(id, alias, &site)? {
+ ToolRoute::Adhoc(binding) => self.prepare_adhoc_call(id, &binding, args, &site),
ToolRoute::Catalog => {
self.prepare_catalog_call(id, alias, args, site)?;
Ok(ToolCallDispatch::Issued)
@@ -378,55 +379,4 @@ impl Scheduler {
self.issue(id, effect, resume);
Ok(())
}
-
- /// Dispatches a `local_tool_done` request: closes the chain's
- /// innermost open local tool call and answers it. A returned text
- /// reports `TOOL_CALL_SUCCEEDED` and a trusted `ToolResult` - the
- /// prompt author wrote the handler, so its output passes verbatim -
- /// under the call id (or none for a script call) and the turn recorded
- /// at dispatch, then resumes as the text. A rejected return reports
- /// `TOOL_CALL_FAILED` and resumes as its error. A raise reports
- /// `TOOL_CALL_FAILED` and resumes empty: the shim raises the handler's
- /// own value in its place.
- ///
- /// # Errors
- /// Returns [`Error::Internal`] when the chain has no frame or no open
- /// local call, which only a shim bug produces.
- pub(super) fn dispatch_local_tool_done(
- &mut self,
- id: ChainIndex,
- outcome: LocalToolOutcome,
- ) -> Result<()> {
- let chain = &mut self.chains[id.index()];
- let emitter = Arc::clone(chain.ctx.emitter());
- let section = chain.section_name().to_owned();
- let call = chain.frame_mut()?.pop_local_call().ok_or(Error::internal(
- "a local tool's completion closes the call that opened it",
- ))?;
- let answer = match outcome {
- LocalToolOutcome::Returned(text) => {
- emitter.report(§ion, lifecycle::TOOL_CALL_SUCCEEDED);
- emitter.tool_result(
- §ion,
- call.report.turn,
- call.call_id.as_deref().unwrap_or(""),
- &call.alias,
- None,
- &text,
- OutputTrust::Trusted,
- );
- Ok(ToolCallOutcome::Plain(text))
- }
- LocalToolOutcome::BadReturn(error) => {
- emitter.report(§ion, lifecycle::TOOL_CALL_FAILED);
- Err(Error::from(error))
- }
- LocalToolOutcome::Raised => {
- emitter.report(§ion, lifecycle::TOOL_CALL_FAILED);
- Ok(ToolCallOutcome::Plain(String::new()))
- }
- };
- self.answer_inline(id, Answer::ToolCallResult(answer));
- Ok(())
- }
}
diff --git a/crates/runvil-internal/engine/src/execute/scope.rs b/crates/runvil-internal/engine/src/execute/scope.rs
index 9b3fd31d4..1af4745a4 100644
--- a/crates/runvil-internal/engine/src/execute/scope.rs
+++ b/crates/runvil-internal/engine/src/execute/scope.rs
@@ -6,23 +6,23 @@ use runvil_model_client::detail;
use runvil_types::emitter::Emitter;
use runvil_types::event::lifecycle;
-use crate::lua::{RenderedTools, ToolBinding};
-use crate::model::ToolSchema;
+use crate::lua::{Advertised, RenderedTools, ToolBinding};
use crate::{Error, Result};
-/// Builds the section's rendered tool list under the validation boundary
-/// pair, reported through the chain's `emitter` under `section`.
+/// Builds the section's rendered tool list from its static bindings,
+/// adhoc tools included, under the validation boundary pair, reported
+/// through the chain's `emitter` under `section`. The dynamic list is left
+/// empty for the caller to fill.
///
/// # Errors
/// Returns the schema-construction error of [`prepare_scoped_tools`].
pub(super) fn prepare_effective_scope(
bindings: &[ToolBinding],
- local_schemas: &[ToolSchema],
emitter: &Emitter,
section: &str,
) -> Result {
emitter.report(section, lifecycle::TOOL_SCOPE_VALIDATION_STARTED);
- let result = prepare_scoped_tools(bindings, local_schemas);
+ let result = prepare_scoped_tools(bindings);
emitter.report(
section,
if result.is_ok() {
@@ -34,21 +34,10 @@ pub(super) fn prepare_effective_scope(
result
}
-pub(super) fn prepare_scoped_tools(
- bindings: &[ToolBinding],
- local_schemas: &[ToolSchema],
-) -> Result {
- let mut schemas = Vec::with_capacity(bindings.len() + local_schemas.len());
+pub(super) fn prepare_scoped_tools(bindings: &[ToolBinding]) -> Result {
+ let mut schemas = Vec::with_capacity(bindings.len());
let mut dispatch = BTreeMap::new();
for binding in bindings {
- // A local alias may equal an offered tool's wire name; the local
- // tool wins.
- if local_schemas
- .iter()
- .any(|schema| schema.name() == binding.alias())
- {
- continue;
- }
// Build every advertised schema through the validated constructor,
// so an unusable wire name or a non-object JSON Schema is refused here
// rather than sent to the model.
@@ -62,14 +51,17 @@ pub(super) fn prepare_scoped_tools(
source: Box::new(error),
})?;
schemas.push(schema);
- dispatch.insert(binding.alias().to_owned(), Some(binding.id().clone()));
- }
- // Local tools are prompt-author Lua functions with no live implementation;
- // the `tool_call` arm answers their calls on the section VM. The alias
- // was validated at `tools.offer_local` registration.
- for schema in local_schemas {
- dispatch.insert(schema.name().to_owned(), None);
- schemas.push(schema.clone());
+ dispatch.insert(
+ binding.alias().to_owned(),
+ Advertised {
+ id: binding.id().clone(),
+ vendor: binding.vendor().map(str::to_owned),
+ },
+ );
}
- Ok(RenderedTools { schemas, dispatch })
+ Ok(RenderedTools {
+ schemas,
+ dispatch,
+ dynamic: Vec::new(),
+ })
}
diff --git a/crates/runvil-internal/engine/src/execute/section_context-construct.rs b/crates/runvil-internal/engine/src/execute/section_context-construct.rs
index 1c1193d53..0fe7a0dda 100644
--- a/crates/runvil-internal/engine/src/execute/section_context-construct.rs
+++ b/crates/runvil-internal/engine/src/execute/section_context-construct.rs
@@ -144,7 +144,7 @@ impl SectionContext {
sys,
item: seed.item,
counts: None,
- local_calls: Vec::new(),
+ adhoc_calls: Vec::new(),
emitter: Arc::clone(ctx.emitter()),
turns: Arc::clone(ctx.turns()),
})
@@ -218,7 +218,7 @@ impl SectionContext {
sys,
item: None,
counts: None,
- local_calls: Vec::new(),
+ adhoc_calls: Vec::new(),
emitter: Arc::clone(ctx.emitter()),
turns: Arc::clone(ctx.turns()),
})
diff --git a/crates/runvil-internal/engine/src/execute/section_context.rs b/crates/runvil-internal/engine/src/execute/section_context.rs
index 922ad968d..3a81a1509 100644
--- a/crates/runvil-internal/engine/src/execute/section_context.rs
+++ b/crates/runvil-internal/engine/src/execute/section_context.rs
@@ -25,8 +25,9 @@ use std::sync::atomic::AtomicU32;
use runvil_types::emitter::Emitter;
use runvil_types::event::lifecycle;
+use runvil_types::tools::ToolId;
-use crate::lua::{ProseState, ScriptReport, SectionVm, ToolBinding, ToolCallCounts};
+use crate::lua::{ProseState, ScriptReport, SectionVm, ToolCallCounts};
use crate::{Error, Result, subst};
use super::context::RunState;
@@ -43,11 +44,13 @@ pub(super) struct TaskSeed {
pub(super) index: Option,
}
-/// One local tool call whose handler is running in the frame's block
+/// One adhoc tool call whose handler is running in the frame's block
/// coroutine: opened when the `tool_call` is answered with the handler,
-/// closed by the shim's `local_tool_done`, which reports under it.
-pub(super) struct LocalCall {
- /// The local tool's alias.
+/// closed by the shim's `adhoc_tool_done`, which reports under it.
+pub(super) struct AdhocCall {
+ /// The adhoc tool's id, which its result reports under.
+ pub(super) tool: ToolId,
+ /// The adhoc tool's wire name.
pub(super) alias: String,
/// The model-issued call id, `None` for a script call.
pub(super) call_id: Option,
@@ -55,6 +58,10 @@ pub(super) struct LocalCall {
/// model turn the call was made in even when the handler runs model
/// rounds of its own.
pub(super) report: ScriptReport,
+ /// Whether the handler's own `tools.call` received a listing while
+ /// this call was the frame's innermost open one, so its result is
+ /// wrapped and reported untrusted.
+ pub(super) listing: bool,
}
/// One section entry's owned frame within a run.
@@ -86,10 +93,10 @@ pub(super) struct SectionContext {
/// The per-section tool-call counts, installed at the first
/// script-initiated `tools.call`.
counts: Option,
- /// The local tool calls whose handlers are running, innermost last: a
- /// handler that calls another local tool opens a nested entry, and
- /// each `local_tool_done` closes the innermost.
- local_calls: Vec,
+ /// The adhoc tool calls whose handlers are running, innermost last: a
+ /// handler that calls another adhoc tool opens a nested entry, and
+ /// each `adhoc_tool_done` closes the innermost.
+ adhoc_calls: Vec,
/// The frame's task-scoped event emitter: the chain's own, so every
/// report the frame makes - the teardown boundary, the completion -
/// is stamped with the chain's task.
@@ -183,8 +190,9 @@ impl SectionContext {
/// The frame's tool-call counts for a script-initiated dispatch,
/// running the same one-time scope install the first prose block
/// performs (the counts and the Lua `tools.calls` table, the model
- /// freeze, the `sys.model` enrichment), then seeding the id of any tool
- /// the effective scope has gained since. The returned handle shares the
+ /// freeze, the `sys.model` enrichment), then seeding any of `ids` not
+ /// seeded yet. `ids` is the section's live scope before its first
+ /// render and its rendered list after. The returned handle shares the
/// installed counts, so the dispatch task increments them off the
/// driver thread.
///
@@ -194,7 +202,7 @@ impl SectionContext {
pub(super) fn script_call_counts(
&mut self,
ctx: &RunState,
- effective: &[ToolBinding],
+ ids: &[ToolId],
) -> Result {
let Self {
vm, sys, counts, ..
@@ -204,24 +212,32 @@ impl SectionContext {
"the section frame's VM lives until the frame's own drop",
));
};
- install_section_scope(vm, ctx, sys, counts, effective)?;
+ install_section_scope(vm, ctx, sys, counts, ids)?;
let counts = counts
.as_ref()
.ok_or(Error::internal("the scope install seeds the counts"))?;
- for binding in effective {
- counts.ensure(&binding.id().to_string())?;
+ for id in ids {
+ counts.ensure(&id.to_string())?;
}
Ok(counts.clone())
}
- /// Opens a local tool call whose handler the shim is about to run.
- pub(super) fn push_local_call(&mut self, call: LocalCall) {
- self.local_calls.push(call);
+ /// Opens an adhoc tool call whose handler the shim is about to run.
+ pub(super) fn push_adhoc_call(&mut self, call: AdhocCall) {
+ self.adhoc_calls.push(call);
}
- /// Closes the innermost open local tool call; `None` when none is open.
- pub(super) fn pop_local_call(&mut self) -> Option {
- self.local_calls.pop()
+ /// Closes the innermost open adhoc tool call; `None` when none is open.
+ pub(super) fn pop_adhoc_call(&mut self) -> Option {
+ self.adhoc_calls.pop()
+ }
+
+ /// Marks the innermost open adhoc tool call as having received a
+ /// listing; a frame with no open call marks nothing.
+ pub(super) fn mark_listing(&mut self) {
+ if let Some(call) = self.adhoc_calls.last_mut() {
+ call.listing = true;
+ }
}
}
@@ -252,9 +268,10 @@ fn prose_renderer(
/// Installs the section's one-time tool-call counts and model resolution,
/// gated on the counts slot: the first consumer - the section's first
/// script-initiated `tools.call` - performs the install, and every later
-/// call is a no-op. The counts install backs the Lua `tools.calls` table;
-/// the model resolution freezes the section's binding and enriches
-/// `sys.model`.
+/// call is a no-op. The counts install backs the Lua `tools.calls` table,
+/// seeded with `ids`: the section's live scope before its first render
+/// and its rendered list after. The model resolution freezes the
+/// section's binding and enriches `sys.model`.
///
/// # Errors
/// Returns the [`Error`] of the counts install, the model resolution, or
@@ -264,12 +281,12 @@ fn install_section_scope(
ctx: &RunState,
sys: &mut serde_json::Value,
counts: &mut Option,
- effective_bindings: &[ToolBinding],
+ ids: &[ToolId],
) -> Result<()> {
if counts.is_some() {
return Ok(());
}
- *counts = Some(vm.install_tool_call_counts(effective_bindings)?);
+ *counts = Some(vm.install_tool_call_counts(ids)?);
let resolved_model = crate::lua::resolve_model_binding(ctx.models(), vm.model_runtime())?;
if let Some(binding) = resolved_model.as_ref() {
let current = vm.current_sys(sys)?;
diff --git a/crates/runvil-internal/engine/src/execute/tests.rs b/crates/runvil-internal/engine/src/execute/tests.rs
index 6f0aacaff..bc90f24c8 100644
--- a/crates/runvil-internal/engine/src/execute/tests.rs
+++ b/crates/runvil-internal/engine/src/execute/tests.rs
@@ -161,6 +161,7 @@ const STORE_SECTIONS: &str = "---\nname: t\ndescription: d\nrunvil: 0\n---\n\n\
## First\n\n```lua\nstore.write('state.txt', 'first')\n```\n\n\
## Second\n\n```lua\nstore.append('state.txt', '\\nsecond')\nreturn \"second\"\n```\n";
+mod adhoc_tools;
mod batch_turn;
mod chat_arm;
mod chat_record_rebuild;
@@ -168,13 +169,13 @@ mod chat_scope;
mod compaction;
mod debug_and_counts;
mod effects;
+mod event_vendors;
mod exec_flow;
mod exit_rules;
mod fanout_acceptance;
mod full_id_calls;
mod happens_before;
mod live_infer;
-mod local_tools;
mod model_and_reply;
mod models_compact;
mod models_loop;
@@ -198,6 +199,7 @@ mod tasks;
mod timeouts;
mod tool_call_access;
mod tool_call_arm;
+mod tool_listings;
mod tool_loop;
mod tool_scoping;
mod unified_pipeline;
diff --git a/crates/runvil-internal/engine/src/execute/tests/adhoc_tools-wrappers.rs b/crates/runvil-internal/engine/src/execute/tests/adhoc_tools-wrappers.rs
new file mode 100644
index 000000000..29341c49f
--- /dev/null
+++ b/crates/runvil-internal/engine/src/execute/tests/adhoc_tools-wrappers.rs
@@ -0,0 +1,90 @@
+//! Tests for an adhoc tool that wraps a catalog tool: it renders the
+//! catalog tool's description and schema unchanged, and a model's call to
+//! it gives the model the same result text as a call to the catalog tool.
+
+use runvil_types::event::Event;
+
+use super::super::fixtures::untrusted_echo_tool;
+use super::*;
+
+/// The wrapper of the untrusted catalog tool `t`, offered as `search`,
+/// whose function returns `tools.call(t, args)`.
+const WRAPPER: &str = "local t = tools.get('tools/untrusted_echo')
+ tools.offer(tools.adhoc({ name = 'search', description = t.description, parameters = t.parameters }, function(args)
+ return tools.call(t, args)
+ end))";
+
+/// One loop over a section that runs `offer`, in which the model calls
+/// `name` with `value = 'hi'` and then replies.
+fn called(offer: &str, name: &str) -> (Trace, Vec) {
+ let gateway = ScriptedChat::new(vec![
+ calls(&[("call_1", name, r#"{"value":"hi"}"#)]),
+ text("done"),
+ ]);
+ let source = one_section(&format!(
+ "{offer}
+ messages:user('search')
+ models.loop()
+ return 'ok'"
+ ));
+ let trace = loop_scenario(source)
+ .offer("untrusted_echo", untrusted_echo_tool())
+ .chat(&gateway)
+ .run();
+ assert_eq!(trace.text(), "ok");
+ (trace, gateway.requests())
+}
+
+#[test]
+fn a_wrapper_renders_the_catalog_tools_description_and_schema_unchanged() {
+ let (_, direct) = called("tools.offer('tools/untrusted_echo')", "untrusted_echo");
+ let (_, through) = called(WRAPPER, "search");
+ let (catalog, wrapper) = (&direct[0].tools[0], &through[0].tools[0]);
+ assert_eq!(wrapper.name(), "search");
+ assert_eq!(
+ wrapper.description(),
+ catalog.description(),
+ "the description is the catalog text, never in the envelope"
+ );
+ assert_eq!(
+ serde_json::to_string(wrapper.parameters()).expect("a schema serializes"),
+ serde_json::to_string(catalog.parameters()).expect("a schema serializes"),
+ "the schema is the same text"
+ );
+}
+
+#[test]
+fn a_model_call_to_the_wrapper_gives_the_model_the_catalog_calls_text_byte_for_byte() {
+ let (_, direct) = called("tools.offer('tools/untrusted_echo')", "untrusted_echo");
+ let (trace, through) = called(WRAPPER, "search");
+ let text = last_tool_turn_content(&direct);
+ assert!(
+ text.contains(" Some((
+ tool.as_ref().map(ToString::to_string),
+ vendor.clone(),
+ *trusted,
+ )),
+ _ => None,
+ })
+ .expect("the wrapper's call reports its result");
+ assert_eq!(
+ result,
+ (Some("adhoc/search".to_owned()), None, true),
+ "the result names the adhoc tool's id and no vendor, and is trusted because \
+ the author's function produced the text"
+ );
+}
diff --git a/crates/runvil-internal/engine/src/execute/tests/local_tools.rs b/crates/runvil-internal/engine/src/execute/tests/adhoc_tools.rs
similarity index 68%
rename from crates/runvil-internal/engine/src/execute/tests/local_tools.rs
rename to crates/runvil-internal/engine/src/execute/tests/adhoc_tools.rs
index c1b29553e..c2b60d8e4 100644
--- a/crates/runvil-internal/engine/src/execute/tests/local_tools.rs
+++ b/crates/runvil-internal/engine/src/execute/tests/adhoc_tools.rs
@@ -1,10 +1,12 @@
-//! Tests for `tools.offer_local`: the registration rules run end to end, and
-//! the `models.loop` shim's local-tool rounds are driven at prompt level,
-//! so a model-issued call to a local tool runs its handler inside the
-//! block coroutine - store calls included - and its trusted result is sent
-//! back to the model verbatim. `jump` is refused only while a handler
-//! runs, even through a saved reference. The refusal of an offer once the
-//! section's tool list is rendered sits in `rendered_tools`.
+//! Tests for adhoc tools defined with `tools.adhoc` and offered with
+//! `tools.offer`: the definition rules run end to end, and the
+//! `models.loop` shim's adhoc-tool rounds are driven at prompt level, so a
+//! model-issued call to an adhoc tool runs its handler inside the block
+//! coroutine - store calls included - and its trusted result is sent back
+//! to the model verbatim. `jump` is refused only while a handler runs,
+//! even through a saved reference. An adhoc tool answers a model's call
+//! only when offered. The refusal of an offer once the section's tool list
+//! is rendered sits in `rendered_tools`.
use runvil_parser::test_support::{one_section, prompt};
@@ -14,14 +16,14 @@ use super::models_loop::loop_scenario;
use super::tool_call_arm::{ToolRecorder, tool_result_lines};
use super::*;
-/// The `grab` local tool registration the loop tests open with, followed
-/// by one loop over a single user message; `handler` is the Lua body of
-/// the handler function, given `args`.
+/// The `grab` adhoc tool definition and offer the loop tests open with,
+/// followed by one loop over a single user message; `handler` is the Lua
+/// body of the handler function, given `args`.
fn grab_loop(handler: &str) -> String {
one_section(&format!(
- "tools.offer_local('grab', 'Grab a value', {{ value = 'string' }}, function(args)
+ "tools.offer(tools.adhoc({{ name = 'grab', description = 'Grab a value', parameters = {{ value = 'string' }} }}, function(args)
{handler}
- end)
+ end))
messages:user('Use the tool.')
models.loop()
return messages[#messages].content"
@@ -33,7 +35,7 @@ fn grab_loop(handler: &str) -> String {
const OTHER: (&str, &str) = ("Other", "return 'jumped'");
#[test]
-fn local_tool_handler_result_returns_to_the_model() {
+fn adhoc_tool_handler_result_returns_to_the_model() {
let gateway = ScriptedChat::new(vec![
calls(&[("call_1", "grab", "{\"value\":\"hi\"}")]),
text("final answer"),
@@ -60,7 +62,7 @@ fn local_tool_handler_result_returns_to_the_model() {
}
#[test]
-fn local_tool_multiple_calls_in_one_response_all_run() {
+fn adhoc_tool_multiple_calls_in_one_response_all_run() {
let gateway = ScriptedChat::new(vec![
calls(&[
("c1", "grab", "{\"value\":\"a\"}"),
@@ -70,10 +72,10 @@ fn local_tool_multiple_calls_in_one_response_all_run() {
]);
let source = one_section(
"local calls = {}
- tools.offer_local('grab', 'Grab a value', { value = 'string' }, function(args)
+ tools.offer(tools.adhoc({ name = 'grab', description = 'Grab a value', parameters = { value = 'string' } }, function(args)
calls[#calls + 1] = args.value
return 'ok ' .. args.value
- end)
+ end))
messages:user('Use the tool.')
models.loop()
return table.concat(calls, ',') .. '|' .. messages[#messages].content",
@@ -98,7 +100,7 @@ fn local_tool_multiple_calls_in_one_response_all_run() {
}
#[test]
-fn local_tool_handler_error_surfaces_as_a_tool_failure() {
+fn adhoc_tool_handler_error_surfaces_as_a_tool_failure() {
let gateway = ScriptedChat::new(vec![
calls(&[("call_1", "grab", "{\"value\":\"hi\"}")]),
text("unreachable"),
@@ -130,7 +132,7 @@ fn local_tool_handler_error_surfaces_as_a_tool_failure() {
}
#[test]
-fn cancel_during_a_looping_local_tool_handler_returns_promptly() {
+fn cancel_during_a_looping_adhoc_tool_handler_returns_promptly() {
// The round's answer hands the model's call to the looping handler in
// the next step. A cancel landing before that step starts ends the run
// the same way, and a hang fails through nextest's timeout.
@@ -174,9 +176,9 @@ fn a_handler_that_calls_jump_fails_the_run() {
calls(&[("call_1", "grab", "{\"value\":\"hi\"}")]),
text("unreachable"),
]);
- let only = "tools.offer_local('grab', 'Grab a value', { value = 'string' }, function(args)
+ let only = "tools.offer(tools.adhoc({ name = 'grab', description = 'Grab a value', parameters = { value = 'string' } }, function(args)
jump('## Other')
- end)
+ end))
messages:user('Use the tool.')
models.loop()
return 'no jump'";
@@ -190,20 +192,20 @@ fn a_handler_that_calls_jump_fails_the_run() {
);
}
-/// The start of the message `jump` fails with inside a local tool handler.
-const JUMP_REFUSAL: &str = "jump is unavailable inside a local tool handler";
+/// The start of the message `jump` fails with inside an adhoc tool handler.
+const JUMP_REFUSAL: &str = "jump is unavailable inside an adhoc tool handler";
-/// The `grab` registration whose handler calls a `jump` reference the
-/// block saved before registering it.
+/// The `grab` definition whose handler calls a `jump` reference the
+/// block saved before defining it.
const SAVED_JUMP_GRAB: &str = "local j = jump\n\
- tools.offer_local('grab', 'Grab a value', { value = 'string' }, function(args)\n\
+ tools.offer(tools.adhoc({ name = 'grab', description = 'Grab a value', parameters = { value = 'string' } }, function(args)\n\
j('## Other')\n\
- end)\n";
+ end))\n";
#[test]
fn a_saved_jump_reference_is_refused_in_a_handler_the_script_calls() {
let only = format!(
- "{SAVED_JUMP_GRAB}tools.call('grab', {{ value = 'hi' }})\n\
+ "{SAVED_JUMP_GRAB}tools.call('adhoc/grab', {{ value = 'hi' }})\n\
return 'no jump'"
);
let trace = loop_scenario(prompt("", &[("Only", &only), OTHER])).run();
@@ -238,7 +240,7 @@ fn a_saved_jump_reference_is_refused_in_a_handler_the_model_calls() {
#[test]
fn a_caller_that_catches_the_jump_refusal_continues_the_block() {
let only = format!(
- "{SAVED_JUMP_GRAB}local ok, err = pcall(tools.call, 'grab', {{ value = 'hi' }})\n\
+ "{SAVED_JUMP_GRAB}local ok, err = pcall(tools.call, 'adhoc/grab', {{ value = 'hi' }})\n\
assert(not ok, 'the refusal reaches the call site')\n\
assert(tostring(err):find('{JUMP_REFUSAL}', 1, true), tostring(err))\n\
return 'no jump'"
@@ -250,15 +252,15 @@ fn a_caller_that_catches_the_jump_refusal_continues_the_block() {
#[test]
fn jump_stays_refused_in_an_outer_handler_after_an_inner_one_returns() {
let only = format!(
- "tools.offer_local('inner', 'Inner', {{}}, function() return 'inner' end)
- tools.offer_local('outer', 'Outer', {{}}, function()
- local inner = tools.call('inner', {{}})
+ "tools.offer(tools.adhoc({{ name = 'inner', description = 'Inner' }}, function() return 'inner' end))
+ tools.offer(tools.adhoc({{ name = 'outer', description = 'Outer' }}, function()
+ local inner = tools.call('adhoc/inner', {{}})
local ok, err = pcall(jump, '## Other')
assert(not ok, 'jump is still refused in the outer handler')
assert(tostring(err):find('{JUMP_REFUSAL}', 1, true), tostring(err))
return inner
- end)
- assert(tools.call('outer', {{}}) == 'inner', 'the outer handler returns')
+ end))
+ assert(tools.call('adhoc/outer', {{}}) == 'inner', 'the outer handler returns')
jump('## Other')"
);
let trace = loop_scenario(prompt("", &[("Only", &only), OTHER])).run();
@@ -271,9 +273,9 @@ fn jump_works_in_the_same_block_after_the_loop_returns() {
calls(&[("call_1", "grab", "{\"value\":\"hi\"}")]),
text("final answer"),
]);
- let only = "tools.offer_local('grab', 'Grab a value', { value = 'string' }, function(args)
+ let only = "tools.offer(tools.adhoc({ name = 'grab', description = 'Grab a value', parameters = { value = 'string' } }, function(args)
return 'got ' .. args.value
- end)
+ end))
messages:user('Use the tool.')
models.loop()
jump('## Other')";
@@ -310,7 +312,37 @@ fn a_handler_returning_a_table_raises_and_is_observed_as_a_failure() {
}
#[test]
-fn a_local_tool_may_take_an_offered_wire_name_and_wins_in_scope() {
+fn a_model_call_to_an_offered_catalog_name_never_reaches_an_unoffered_adhoc_tool_of_that_name() {
+ let gateway = ScriptedChat::new(vec![
+ calls(&[("call_1", "tools_concrete", "{}")]),
+ text("final answer"),
+ ]);
+ let (tool, called) = scoped_tool("concrete", "Concrete description.");
+ let source = one_section(
+ "tools.adhoc({ name = 'tools_concrete', description = 'Local concrete' }, function() return 'local' end)
+ tools.offer('tools/concrete')
+ messages:user('Use the tool.')
+ models.loop()
+ return messages[#messages].content",
+ );
+ let trace = loop_scenario(source)
+ .offer("tools_concrete", tool)
+ .chat(&gateway)
+ .run();
+ assert_eq!(trace.text(), "final answer");
+ let bodies = gateway.requests();
+ assert_eq!(bodies[0].tools.len(), 1);
+ assert_eq!(bodies[0].tools[0].description(), "Concrete description.");
+ assert_eq!(
+ called.load(Ordering::SeqCst),
+ 1,
+ "the catalog tool answers the model's call"
+ );
+ assert_ne!(last_tool_turn_content(&bodies), "local");
+}
+
+#[test]
+fn an_adhoc_tool_may_take_an_offered_wire_name_and_wins_in_scope() {
let gateway = ScriptedChat::new(vec![
calls(&[("call_1", "tools_concrete", "{}")]),
text("final answer"),
@@ -318,7 +350,7 @@ fn a_local_tool_may_take_an_offered_wire_name_and_wins_in_scope() {
let (tool, called) = scoped_tool("concrete", "Concrete description.");
let source = one_section(
"tools.offer('tools/concrete')
- tools.offer_local('tools_concrete', 'Local concrete', {}, function() return 'local' end)
+ tools.offer(tools.adhoc({ name = 'tools_concrete', description = 'Local concrete' }, function() return 'local' end))
messages:user('Use the tool.')
models.loop()
return messages[#messages].content",
@@ -344,15 +376,20 @@ fn a_local_tool_may_take_an_offered_wire_name_and_wins_in_scope() {
}
#[test]
-fn local_tool_alias_cannot_be_registered_twice() {
+fn an_adhoc_tool_name_cannot_be_defined_twice() {
let source = one_section(
- "tools.offer_local('grab', 'First grab', {}, function() return 'first' end)
- tools.offer_local('grab', 'Second grab', {}, function() return 'second' end)",
+ "tools.offer(tools.adhoc({ name = 'grab', description = 'First grab' }, function() return 'first' end))
+ tools.offer(tools.adhoc({ name = 'grab', description = 'Second grab' }, function() return 'second' end))",
);
let trace = Scenario::new(source).run();
let error = trace.error();
assert!(
- error.to_string().contains("is already registered"),
- "the error must identify the duplicate local alias: {error}"
+ error
+ .to_string()
+ .contains("tools.adhoc name \"grab\" is already registered"),
+ "the error must identify the duplicate adhoc name: {error}"
);
}
+
+#[path = "adhoc_tools-wrappers.rs"]
+mod wrappers;
diff --git a/crates/runvil-internal/engine/src/execute/tests/batch_turn.rs b/crates/runvil-internal/engine/src/execute/tests/batch_turn.rs
index 728cabf26..3879489a4 100644
--- a/crates/runvil-internal/engine/src/execute/tests/batch_turn.rs
+++ b/crates/runvil-internal/engine/src/execute/tests/batch_turn.rs
@@ -1,9 +1,9 @@
//! Tests for the turn a model-issued tool result reports: every result in
//! a batch carries the turn of the round that requested the batch, even
-//! when an earlier local handler in that batch runs model rounds of its
+//! when an earlier adhoc handler in that batch runs model rounds of its
//! own - through `models.infer` or a `call` into a section that runs one -
//! and advances the chain's turn counter before the later calls dispatch.
-//! Bound tools and local tools both report the requesting round's turn.
+//! Bound tools and adhoc tools both report the requesting round's turn.
//! A handler or a compactor cannot start its own loop while a loop runs in
//! the section; once no loop runs, the next one starts normally.
@@ -94,15 +94,15 @@ impl Turns {
}
}
-/// The block every test here runs: registers `grab` with `handler` as its
+/// The block every test here runs: defines and offers `grab` with `handler` as its
/// body, then one loop over a single user message, returning the final
/// record's text. `setup` runs first.
fn grab_block(setup: &str, handler: &str) -> String {
format!(
"{setup}\
- tools.offer_local('grab', 'Grab a value', {{ value = 'string' }}, function(args)\n\
+ tools.offer(tools.adhoc({{ name = 'grab', description = 'Grab a value', parameters = {{ value = 'string' }} }}, function(args)\n\
{handler}\n\
- end)\n\
+ end))\n\
messages:user('Use the tools.')\n\
models.loop()\n\
return messages[#messages].content"
@@ -179,11 +179,11 @@ fn a_handlers_loop_during_a_loop_raises_loop_running_as_a_lua_error() {
]);
let source = one_section(&with_run_loop(
"local refusal\n\
- tools.offer_local('grab', 'Grab a value', { value = 'string' }, function()\n\
+ tools.offer(tools.adhoc({ name = 'grab', description = 'Grab a value', parameters = { value = 'string' } }, function()\n\
local ok, err = pcall(models.loop)\n\
refusal = tostring(ok) .. '|' .. err.kind .. '|' .. tostring(err)\n\
return 'refused'\n\
- end)\n\
+ end))\n\
local final = run_loop('Use the tools.')\n\
return refusal .. '|' .. final",
));
@@ -250,10 +250,10 @@ fn a_loop_after_an_earlier_loop_raised_under_pcall_runs_normally() {
fn a_handlers_loop_runs_normally_when_tools_call_reaches_it_outside_any_loop() {
let gateway = ScriptedChat::new(vec![text("inner reply")]);
let source = one_section(&with_run_loop(
- "tools.offer_local('grab', 'Grab a value', { value = 'string' }, function(args)\n\
+ "tools.offer(tools.adhoc({ name = 'grab', description = 'Grab a value', parameters = { value = 'string' } }, function(args)\n\
return run_loop(args.value)\n\
- end)\n\
- return tools.call('grab', { value = 'inner' })",
+ end))\n\
+ return tools.call('adhoc/grab', { value = 'inner' })",
));
let trace = loop_scenario(source).chat(&gateway).run();
assert_eq!(trace.text(), "inner reply");
diff --git a/crates/runvil-internal/engine/src/execute/tests/chat_arm.rs b/crates/runvil-internal/engine/src/execute/tests/chat_arm.rs
index 3cb9d0ca5..d5ee82d22 100644
--- a/crates/runvil-internal/engine/src/execute/tests/chat_arm.rs
+++ b/crates/runvil-internal/engine/src/execute/tests/chat_arm.rs
@@ -143,7 +143,7 @@ fn a_tool_round_reports_the_batch_before_the_shim_dispatches_it() {
}
#[test]
-fn a_batch_names_the_tool_behind_a_bound_alias_and_none_behind_a_local_one() {
+fn a_batch_names_the_tool_behind_each_wire_name_an_adhoc_one_included() {
let gateway = ScriptedChat::new(vec![
calls(&[
("call_1", "grab", "{\"value\":\"x\"}"),
@@ -153,9 +153,9 @@ fn a_batch_names_the_tool_behind_a_bound_alias_and_none_behind_a_local_one() {
]);
let source = one_section(
"tools.offer('tools/echo')
- tools.offer_local('grab', 'Local grab', { value = 'string' }, function(args)
+ tools.offer(tools.adhoc({ name = 'grab', description = 'Local grab', parameters = { value = 'string' } }, function(args)
return 'grabbed ' .. args.value
- end)
+ end))
messages:user('use both tools')
models.loop()
return 'ok'",
@@ -174,9 +174,10 @@ fn a_batch_names_the_tool_behind_a_bound_alias_and_none_behind_a_local_one() {
&& calls
.iter()
.map(|call| call.tool.as_ref().map(ToString::to_string))
- .eq([None, Some("tools/echo".to_owned())])
+ .eq([Some("adhoc/grab".to_owned()), Some("tools/echo".to_owned())])
+ && calls.iter().all(|call| call.vendor.is_none())
)),
- "the bound alias names its tool and the local one names none: {events:?}"
+ "each wire name names its tool, and neither call names a vendor: {events:?}"
);
}
diff --git a/crates/runvil-internal/engine/src/execute/tests/chat_scope.rs b/crates/runvil-internal/engine/src/execute/tests/chat_scope.rs
index d35c72fe8..4fb84b95d 100644
--- a/crates/runvil-internal/engine/src/execute/tests/chat_scope.rs
+++ b/crates/runvil-internal/engine/src/execute/tests/chat_scope.rs
@@ -1,6 +1,6 @@
//! Tests for the `Chat` arm's tool scope from a section VM: every round
//! sends the section's rendered tool list, its effective scope plus every
-//! local Lua tool at the first round.
+//! adhoc tool at the first round.
use runvil_parser::test_support::one_section;
@@ -9,20 +9,20 @@ use super::models_loop::loop_scenario;
use super::*;
#[test]
-fn a_round_advertises_the_section_scope_with_local_tools() {
+fn a_round_advertises_the_section_scope_with_adhoc_tools() {
let gateway = ScriptedChat::new(vec![
calls(&[("call_1", "grab", "{\"value\":\"x\"}")]),
text("done"),
]);
let source = one_section(
"tools.offer('tools/echo')
- tools.offer_local('grab', 'Local grab', { value = 'string' }, function(args)
+ tools.offer(tools.adhoc({ name = 'grab', description = 'Local grab', parameters = { value = 'string' } }, function(args)
return 'grabbed ' .. args.value
- end)
- messages:user('use the local tool')
+ end))
+ messages:user('use the adhoc tool')
models.loop()
- assert(messages[2].tool_calls[1].name == 'grab', 'a local tool is in the advertised scope')
- assert(messages[3].role == 'tool', 'the shim dispatched the local tool')
+ assert(messages[2].tool_calls[1].name == 'grab', 'an adhoc tool is in the advertised scope')
+ assert(messages[3].role == 'tool', 'the shim dispatched the adhoc tool')
return 'ok'",
);
let trace = loop_scenario(source)
@@ -34,6 +34,6 @@ fn a_round_advertises_the_section_scope_with_local_tools() {
assert_eq!(
body.tool_names(),
["echo", "grab"],
- "the bound scope then the local tools: {body:?}"
+ "the bound scope then the adhoc tools: {body:?}"
);
}
diff --git a/crates/runvil-internal/engine/src/execute/tests/compaction.rs b/crates/runvil-internal/engine/src/execute/tests/compaction.rs
index d99eb0679..7fb0866fe 100644
--- a/crates/runvil-internal/engine/src/execute/tests/compaction.rs
+++ b/crates/runvil-internal/engine/src/execute/tests/compaction.rs
@@ -244,9 +244,9 @@ fn a_compaction_a_restore_and_a_clear_leave_the_rendered_tool_list_attached() {
end, 'restore')
local kept = #messages
models.compact(compactors.clear, 'start over')
- local offered, refusal = pcall(tools.offer_local, 'grab', 'Local grab', {}, function()
+ local offered, refusal = pcall(tools.offer, tools.adhoc({ name = 'grab', description = 'Local grab' }, function()
return ''
- end)
+ end))
return table.concat({
tostring(restored), kept, #messages, tostring(offered), tostring(refusal),
}, '|')",
@@ -257,7 +257,7 @@ fn a_compaction_a_restore_and_a_clear_leave_the_rendered_tool_list_attached() {
.run();
assert_eq!(
trace.text(),
- format!("false|2|0|false|tools.offer_local: {FIXED}")
+ format!("false|2|0|false|tools.offer: {FIXED}")
);
let bodies = gateway.requests();
assert_eq!(bodies.len(), 2, "the overflowed round and its retry");
diff --git a/crates/runvil-internal/engine/src/execute/tests/debug_and_counts.rs b/crates/runvil-internal/engine/src/execute/tests/debug_and_counts.rs
index a6d2107ba..721f496d3 100644
--- a/crates/runvil-internal/engine/src/execute/tests/debug_and_counts.rs
+++ b/crates/runvil-internal/engine/src/execute/tests/debug_and_counts.rs
@@ -191,7 +191,7 @@ fn tool_calls_count_increments_even_when_tool_errors() {
}
#[test]
-fn a_model_call_and_a_script_call_count_under_the_id_and_a_local_tool_under_its_alias() {
+fn a_model_call_a_script_call_and_an_adhoc_tool_each_count_under_the_id() {
let gateway = ScriptedChat::new(vec![
calls(&[
("call_1", "echo", r#"{"value":"model"}"#),
@@ -201,12 +201,12 @@ fn a_model_call_and_a_script_call_count_under_the_id_and_a_local_tool_under_its_
]);
let source = one_section(
"tools.offer('tools/echo')
- tools.offer_local('grab', 'Grab a value', { value = 'string' }, function(args) return 'got ' .. args.value end)
+ tools.offer(tools.adhoc({ name = 'grab', description = 'Grab a value', parameters = { value = 'string' } }, function(args) return 'got ' .. args.value end))
messages:user('ask the model')
models.loop()
tools.call('tools/echo', { value = 'script' })
- local ok = pcall(function() return tools.calls.echo end)
- return tostring(tools.calls['tools/echo']) .. '|' .. tostring(tools.calls.grab) .. '|' .. tostring(ok)",
+ local ok = pcall(function() return tools.calls['echo'] end)
+ return tostring(tools.calls['tools/echo']) .. '|' .. tostring(tools.calls['adhoc/grab']) .. '|' .. tostring(ok)",
);
let trace = loop_scenario(source)
.offer("echo", echo_tool())
@@ -216,10 +216,32 @@ fn a_model_call_and_a_script_call_count_under_the_id_and_a_local_tool_under_its_
trace.text(),
"2|1|false",
"the model's wire-name call and the script's id call count once each under \
- the id, the local tool under its alias, and the wire name is no key"
+ the id, the adhoc tool under its own id, and the wire name is no key"
);
}
+#[test]
+fn an_adhoc_tool_defined_after_the_render_has_no_seeded_count() {
+ let gateway = ScriptedChat::new(vec![text("rendered")]);
+ let source = one_section(
+ "local grab = tools.adhoc({ name = 'grab', description = 'Grab' }, function() return 'got' end)
+ tools.offer(tools.packs.get('adhoc'))
+ messages:user('ask the model')
+ models.loop()
+ tools.adhoc({ name = 'late', description = 'Late' }, function() return 'late' end)
+ tools.call(grab, {})
+ local ok, err = pcall(function() return tools.calls['adhoc/late'] end)
+ assert(not ok, 'a tool the rendered list lacks reads no count')
+ local text = tostring(err)
+ assert(text:find('has no seeded count', 1, true), text)
+ assert(text:find('(an adhoc tool that was neither offered in this section nor called with tools.call)', 1, true), text)
+ assert(tools.calls['adhoc/grab'] == 1, 'grab counts once')
+ return 'ok'",
+ );
+ let trace = loop_scenario(source).chat(&gateway).run();
+ assert_eq!(trace.text(), "ok");
+}
+
#[test]
fn tool_calls_count_zero_for_uncalled_alias_fails_epilog_assert() {
// The first script dispatch installs the counts seeded from the
diff --git a/crates/runvil-internal/engine/src/execute/tests/event_vendors.rs b/crates/runvil-internal/engine/src/execute/tests/event_vendors.rs
new file mode 100644
index 000000000..f947bcb5c
--- /dev/null
+++ b/crates/runvil-internal/engine/src/execute/tests/event_vendors.rs
@@ -0,0 +1,147 @@
+//! Tests for the vendor a tool-call or tool-result event records: the
+//! vendor the caller reported for the answering Pack, for a model call and
+//! a script call to a catalog tool, and none for an adhoc call or a run
+//! given no roster.
+
+use runvil_parser::test_support::one_section;
+use runvil_types::event::Event;
+use runvil_types::packs::PackId;
+
+use super::fixtures::echo_tool;
+use super::models_loop::catalog_scenario;
+use super::*;
+
+/// A section that offers `tools/echo` and an adhoc `grab`, lets the model
+/// call both in one batch, then calls `tools/echo` from the script.
+const BOTH_CALLERS: &str = "tools.offer('tools/echo')
+ tools.offer(tools.adhoc({ name = 'grab', description = 'Local grab', parameters = { value = 'string' } }, function(args)
+ return 'grabbed ' .. args.value
+ end))
+ messages:user('use both tools')
+ models.loop()
+ return tools.call('tools/echo', { value = 'script' })";
+
+/// The run of [`BOTH_CALLERS`] with `tools/echo` in the catalog, its
+/// context edited by `roster`.
+fn both_callers(roster: impl FnOnce(RunContext) -> RunContext + 'static) -> Trace {
+ let gateway = ScriptedChat::new(vec![
+ calls(&[
+ ("call_1", "grab", r#"{"value":"x"}"#),
+ ("call_2", "tools_echo", r#"{"value":"y"}"#),
+ ]),
+ text("done"),
+ ]);
+ let trace = catalog_scenario(one_section(BOTH_CALLERS))
+ .tool(echo_tool())
+ .context(roster)
+ .chat(&gateway)
+ .run();
+ assert_eq!(trace.text(), "echoed: script");
+ trace
+}
+
+/// Each requested call's wire name and vendor, in batch order.
+fn batch_vendors(events: &[Event]) -> Vec<(String, Option)> {
+ events
+ .iter()
+ .find_map(|event| match event {
+ Event::AssistantToolCalls { calls, .. } => Some(
+ calls
+ .iter()
+ .map(|call| (call.name.clone(), call.vendor.clone()))
+ .collect(),
+ ),
+ _ => None,
+ })
+ .unwrap_or_else(|| panic!("the round reports its batch: {events:?}"))
+}
+
+/// Each result's call id, alias, and vendor, sorted by call id.
+fn result_vendors(events: &[Event]) -> Vec<(String, String, Option)> {
+ let mut results: Vec<_> = events
+ .iter()
+ .filter_map(|event| match event {
+ Event::ToolResult {
+ tool_call_id,
+ alias,
+ vendor,
+ ..
+ } => Some((tool_call_id.clone(), alias.clone(), vendor.clone())),
+ _ => None,
+ })
+ .collect();
+ results.sort();
+ results
+}
+
+fn owned(name: &str, vendor: Option<&str>) -> (String, Option) {
+ (name.to_owned(), vendor.map(str::to_owned))
+}
+
+fn result(id: &str, alias: &str, vendor: Option<&str>) -> (String, String, Option) {
+ (id.to_owned(), alias.to_owned(), vendor.map(str::to_owned))
+}
+
+#[test]
+fn a_catalog_call_records_the_vendor_the_caller_reported_and_an_adhoc_call_none() {
+ let tools = PackId::parse("tools").expect("a static valid Pack id");
+ let trace = both_callers(move |ctx| ctx.packs(vec![UsablePack::new(tools, "acme")], vec![]));
+ let events = trace.events();
+ assert_eq!(
+ batch_vendors(events),
+ [owned("grab", None), owned("tools_echo", Some("acme"))],
+ "the model's catalog call names acme and its adhoc call names none"
+ );
+ assert_eq!(
+ result_vendors(events),
+ [
+ result("", "tools_echo", Some("acme")),
+ result("call_1", "grab", None),
+ result("call_2", "tools_echo", Some("acme")),
+ ],
+ "the script's and the model's catalog results name acme, the adhoc result none"
+ );
+}
+
+#[test]
+fn an_adhoc_calls_events_name_its_id() {
+ let trace = both_callers(|ctx| ctx);
+ let events = trace.events();
+ let requested = events.iter().find_map(|event| match event {
+ Event::AssistantToolCalls { calls, .. } => calls
+ .iter()
+ .find(|call| call.name == "grab")
+ .map(|call| call.tool.as_ref().map(ToString::to_string)),
+ _ => None,
+ });
+ let answered = events.iter().find_map(|event| match event {
+ Event::ToolResult {
+ tool_call_id, tool, ..
+ } if tool_call_id == "call_1" => Some(tool.as_ref().map(ToString::to_string)),
+ _ => None,
+ });
+ let id = Some(Some("adhoc/grab".to_owned()));
+ assert_eq!(
+ requested, id,
+ "the requested call names the adhoc tool's id"
+ );
+ assert_eq!(answered, id, "its result names the same id");
+}
+
+#[test]
+fn a_run_given_no_roster_records_no_vendor() {
+ let trace = both_callers(|ctx| ctx);
+ let events = trace.events();
+ assert_eq!(
+ batch_vendors(events),
+ [owned("grab", None), owned("tools_echo", None)]
+ );
+ assert_eq!(
+ result_vendors(events),
+ [
+ result("", "tools_echo", None),
+ result("call_1", "grab", None),
+ result("call_2", "tools_echo", None),
+ ]
+ );
+}
diff --git a/crates/runvil-internal/engine/src/execute/tests/full_id_calls.rs b/crates/runvil-internal/engine/src/execute/tests/full_id_calls.rs
index 35ef31669..5d0f90744 100644
--- a/crates/runvil-internal/engine/src/execute/tests/full_id_calls.rs
+++ b/crates/runvil-internal/engine/src/execute/tests/full_id_calls.rs
@@ -140,17 +140,17 @@ fn a_script_call_advertises_nothing_until_the_tool_is_offered() {
}
#[test]
-fn a_script_call_by_wire_name_or_local_looking_name_is_unbound() {
+fn a_script_call_naming_a_string_without_a_slash_raises_before_any_resolution() {
let source = one_section(
"local wire_ok, wire_err = pcall(tools.call, 'tools_echo', {})\n\
local bare_ok, bare_err = pcall(tools.call, 'echo', {})\n\
- assert(not wire_ok and not bare_ok, 'neither name is a catalog id')\n\
- return wire_err.kind .. ':' .. wire_err.name .. '|' .. bare_err.kind .. ':' .. bare_err.name",
+ assert(not wire_ok and not bare_ok, 'neither name is a tool id')\n\
+ return wire_err.kind .. ':' .. tostring(wire_err) .. '|' .. tostring(bare_err)",
);
let rig = Rig::run(catalog_scenario(source).tool(echo_tool()));
assert_eq!(
rig.trace().text(),
- "unbound_tool:tools_echo|unbound_tool:echo"
+ "lua:tools.call: \"tools_echo\" is not a tool id|tools.call: \"echo\" is not a tool id"
);
assert!(rig.issued().is_empty(), "nothing was issued");
}
diff --git a/crates/runvil-internal/engine/src/execute/tests/model_and_reply.rs b/crates/runvil-internal/engine/src/execute/tests/model_and_reply.rs
index c7ef1aa97..18e2c9525 100644
--- a/crates/runvil-internal/engine/src/execute/tests/model_and_reply.rs
+++ b/crates/runvil-internal/engine/src/execute/tests/model_and_reply.rs
@@ -213,7 +213,7 @@ fn offer_over_an_empty_catalog_fails_the_run_loudly() {
assert!(
error
.to_string()
- .contains("tools.offer: \"web/search\" is not a catalog tool in this run"),
+ .contains("tools.offer: \"web/search\" is not a tool in this run"),
"the error must report the missing tool: {error}"
);
}
@@ -230,7 +230,7 @@ fn offer_after_an_h1_helper_fails_the_run_loudly() {
assert!(
error
.to_string()
- .contains("tools.offer: \"web/search\" is not a catalog tool in this run"),
+ .contains("tools.offer: \"web/search\" is not a tool in this run"),
"the error must report the missing tool: {error}"
);
}
diff --git a/crates/runvil-internal/engine/src/execute/tests/models_compact.rs b/crates/runvil-internal/engine/src/execute/tests/models_compact.rs
index 55b712483..6cb0b8c14 100644
--- a/crates/runvil-internal/engine/src/execute/tests/models_compact.rs
+++ b/crates/runvil-internal/engine/src/execute/tests/models_compact.rs
@@ -67,10 +67,10 @@ fn models_compact_refuses_while_a_loop_its_handler_or_a_compactor_runs() {
local ok, err = pcall(models.compact, compactors.clear, label)
seen[#seen + 1] = label .. ':' .. tostring(ok) .. ':' .. err.kind .. ':' .. tostring(err)
end
- tools.offer_local('probe', 'Probe models.compact', { value = 'string' }, function()
+ tools.offer(tools.adhoc({ name = 'probe', description = 'Probe models.compact', parameters = { value = 'string' } }, function()
refuse('handler')
return 'probed'
- end)
+ end))
messages:user('go')
models.loop()
messages:user(string.rep('x', 100000))
diff --git a/crates/runvil-internal/engine/src/execute/tests/models_loop.rs b/crates/runvil-internal/engine/src/execute/tests/models_loop.rs
index 0970541dd..9f26115aa 100644
--- a/crates/runvil-internal/engine/src/execute/tests/models_loop.rs
+++ b/crates/runvil-internal/engine/src/execute/tests/models_loop.rs
@@ -2,7 +2,7 @@
//! loop over the section's `messages` list. One terminal turn with no
//! tools, repeated model-tool rounds with automatic assistant and
//! tool-result appends, the nil return, explicit terminal removal through
-//! `models.compact`, local and bound tools, the tool list the first loop
+//! `models.compact`, adhoc and bound tools, the tool list the first loop
//! round renders, explicit-handle calls on a
//! frozen binding, and the atomic append of a tool-call batch. The shared
//! loop fixtures (`loop_models`, `loop_scenario`, `catalog_scenario`,
@@ -200,7 +200,7 @@ fn replayed_tool_calls_reach_the_chat_effect_in_the_openai_shape() {
}
#[test]
-fn models_loop_dispatches_local_and_bound_tools() {
+fn models_loop_dispatches_adhoc_and_bound_tools() {
let gateway = ScriptedChat::new(vec![
calls(&[("call_1", "grab", "{\"value\":\"x\"}")]),
calls(&[("call_2", "echo", "{\"value\":\"y\"}")]),
@@ -208,14 +208,14 @@ fn models_loop_dispatches_local_and_bound_tools() {
]);
let source = one_section(
"tools.offer('tools/echo')
- tools.offer_local('grab', 'Local grab', { value = 'string' }, function(args)
+ tools.offer(tools.adhoc({ name = 'grab', description = 'Local grab', parameters = { value = 'string' } }, function(args)
return 'grabbed ' .. args.value
- end)
+ end))
messages:user('use both tools')
models.loop()
assert(#messages == 6, 'both exchanges and the terminal record appended')
- assert(messages[3].content == 'grabbed x', 'the local handler ran on the section VM')
- assert(messages[3].tool_call_id == 'call_1', 'the local result correlates its call')
+ assert(messages[3].content == 'grabbed x', 'the adhoc handler ran on the section VM')
+ assert(messages[3].tool_call_id == 'call_1', 'the adhoc result correlates its call')
assert(messages[5].content == 'echoed: y', 'the bound tool ran through dispatch')
return 'ok'",
);
@@ -228,7 +228,7 @@ fn models_loop_dispatches_local_and_bound_tools() {
assert_eq!(
bodies[0].tools.len(),
2,
- "both the local and the bound tool are advertised: {bodies:?}"
+ "both the adhoc and the bound tool are advertised: {bodies:?}"
);
}
@@ -303,14 +303,14 @@ fn the_author_list_never_shows_a_half_answered_tool_batch() {
let source = one_section(
"messages:user('grab twice')
local seen = {}
- tools.offer_local('grab', 'Local grab', { value = 'string' }, function(args)
+ tools.offer(tools.adhoc({ name = 'grab', description = 'Local grab', parameters = { value = 'string' } }, function(args)
seen[#seen + 1] = #messages
for _, m in ipairs(messages) do
assert(m.tool_calls == nil, 'no assistant call record is visible mid-batch')
assert(m.role ~= 'tool', 'no tool record is visible mid-batch')
end
return 'grabbed ' .. args.value
- end)
+ end))
models.loop()
assert(#seen == 2, 'both calls in the batch ran')
assert(seen[1] == 1 and seen[2] == 1, 'each handler saw only the user message')
diff --git a/crates/runvil-internal/engine/src/execute/tests/models_loop_contract-rounds.rs b/crates/runvil-internal/engine/src/execute/tests/models_loop_contract-rounds.rs
index 3a6f0a7da..32f082743 100644
--- a/crates/runvil-internal/engine/src/execute/tests/models_loop_contract-rounds.rs
+++ b/crates/runvil-internal/engine/src/execute/tests/models_loop_contract-rounds.rs
@@ -1,6 +1,6 @@
//! Contract tests for `models.loop`'s rounds: the clean exit's call
//! count, the batch rule under a raising handler, a dropped model-issued
-//! call, a local tool's return and its cancellation, and the full trace a
+//! call, an adhoc tool's return and its cancellation, and the full trace a
//! run reports for the loop.
use runvil_parser::test_support::{PromptSource, one_section};
@@ -168,11 +168,11 @@ fn a_handler_raising_mid_batch_leaves_the_list_untouched_and_raises_its_own_tabl
let source = one_section(
"local own = { reason = 'mine' }
local count = 0
- tools.offer_local('grab', 'Local grab', { value = 'string' }, function(args)
+ tools.offer(tools.adhoc({ name = 'grab', description = 'Local grab', parameters = { value = 'string' } }, function(args)
count = count + 1
if count == 2 then error(own) end
return 'grabbed ' .. args.value
- end)
+ end))
messages:user('grab twice')
local ok, err = pcall(models.loop)
return tostring(ok) .. '|' .. tostring(err == own) .. '|' .. count \
@@ -227,7 +227,7 @@ fn a_dropped_model_issued_call_raises_cancelled_at_the_loop_call_site() {
}
#[test]
-fn a_local_tools_first_return_value_is_its_text_and_nil_is_empty() {
+fn an_adhoc_tools_first_return_value_is_its_text_and_nil_is_empty() {
let gateway = ScriptedChat::new(vec![
calls(&[
("c1", "none", "{}"),
@@ -237,9 +237,9 @@ fn a_local_tools_first_return_value_is_its_text_and_nil_is_empty() {
text("done"),
]);
let source = one_section(
- "tools.offer_local('none', 'Returns nothing', {}, function() end)
- tools.offer_local('num', 'Returns a number', {}, function() return 42 end)
- tools.offer_local('two', 'Returns two values', {}, function() return 'first', 'second' end)
+ "tools.offer(tools.adhoc({ name = 'none', description = 'Returns nothing' }, function() end))
+ tools.offer(tools.adhoc({ name = 'num', description = 'Returns a number' }, function() return 42 end))
+ tools.offer(tools.adhoc({ name = 'two', description = 'Returns two values' }, function() return 'first', 'second' end))
messages:user('call all three')
models.loop()
return '[' .. messages[3].content .. ']|' .. messages[4].content .. '|' .. messages[5].content",
@@ -249,7 +249,7 @@ fn a_local_tools_first_return_value_is_its_text_and_nil_is_empty() {
}
#[test]
-fn a_local_tool_cancelled_mid_handler_reports_no_failed_tool_call() {
+fn an_adhoc_tool_cancelled_mid_handler_reports_no_failed_tool_call() {
// The cancel lands between steps once the first round is answered, so
// the step that hands the model's call to the looping handler runs
// with the flag already set.
@@ -258,9 +258,9 @@ fn a_local_tool_cancelled_mid_handler_reports_no_failed_tool_call() {
text("unreachable"),
]);
let source = one_section(
- "tools.offer_local('grab', 'Grab a value', { value = 'string' }, function(args)
+ "tools.offer(tools.adhoc({ name = 'grab', description = 'Grab a value', parameters = { value = 'string' } }, function(args)
while true do end
- end)
+ end))
messages:user('Use the tool.')
models.loop()
return 'unreachable'",
@@ -284,7 +284,7 @@ fn a_local_tool_cancelled_mid_handler_reports_no_failed_tool_call() {
}
#[test]
-fn the_scheduler_reports_the_whole_trace_of_a_bound_round_a_local_round_and_a_reply() {
+fn the_scheduler_reports_the_whole_trace_of_a_bound_round_an_adhoc_round_and_a_reply() {
let gateway = ScriptedChat::new(vec![
calls(&[("call_1", "echo", "{\"value\":\"a\"}")]),
calls(&[("call_2", "grab", "{\"value\":\"b\"}")]),
@@ -293,9 +293,9 @@ fn the_scheduler_reports_the_whole_trace_of_a_bound_round_a_local_round_and_a_re
let source = PromptSource::new().title("Loop").section(
"Only",
"tools.offer('tools/echo')
- tools.offer_local('grab', 'Local grab', { value = 'string' }, function(args)
+ tools.offer(tools.adhoc({ name = 'grab', description = 'Local grab', parameters = { value = 'string' } }, function(args)
return 'grabbed ' .. args.value
- end)
+ end))
messages:user('use both tools')
models.loop()
return messages[#messages].content",
diff --git a/crates/runvil-internal/engine/src/execute/tests/offering-packs.rs b/crates/runvil-internal/engine/src/execute/tests/offering-packs.rs
index c4305726a..360a0fd20 100644
--- a/crates/runvil-internal/engine/src/execute/tests/offering-packs.rs
+++ b/crates/runvil-internal/engine/src/execute/tests/offering-packs.rs
@@ -1,4 +1,4 @@
-//! Tests for `packs.offer` across section entries: an offered Pack's
+//! Tests for a Pack offered by id across section entries: an offered Pack's
//! tools reach the rounds of the section entry that offered it, through
//! `require` too, and no other entry's.
@@ -26,12 +26,12 @@ fn an_offered_pack_reaches_only_the_rounds_of_the_section_entry_that_offered_it(
let source = format!(
"---\nname: t\ndescription: d\nrunvil: 0\n---\n\n\
# Packs\n\n\
- ```lua\npacks.offer('kit')\n{h1}```\n\n\
+ ```lua\ntools.offer('kit')\n{h1}```\n\n\
## A\n\n\
```lua\n\
tools.offer('kit/a')\n\
require '## offers'\n\
- packs.offer('kit')\n\
+ tools.offer('kit')\n\
{a}\
call('## Called')\n\
tasks.join({{ tasks.spawn('## Worker') }})\n\
@@ -39,7 +39,7 @@ fn an_offered_pack_reaches_only_the_rounds_of_the_section_entry_that_offered_it(
## B\n\n\
```lua\n{b}return 'ok'\n```\n\n\
## offers\n\n\
- ```lua\npacks.offer('web')\n```\n\n\
+ ```lua\ntools.offer('web')\n```\n\n\
## Called\n\n\
```lua\n{called}return 'called'\n```\n\n\
## Worker\n\n\
diff --git a/crates/runvil-internal/engine/src/execute/tests/offering.rs b/crates/runvil-internal/engine/src/execute/tests/offering.rs
index dd0b4e7f7..d2ccc9efc 100644
--- a/crates/runvil-internal/engine/src/execute/tests/offering.rs
+++ b/crates/runvil-internal/engine/src/execute/tests/offering.rs
@@ -1,6 +1,6 @@
//! Tests for the offering: every catalog tool the run can offer, bound
-//! under its wire name, which `tools.offer` scopes by id or tool object, a
-//! model call resolves by wire name, and a script call resolves by id.
+//! under its wire name, which `tools.offer` scopes by id, Pack, or object,
+//! a model call resolves by wire name, and a script call resolves by id.
use runvil_parser::test_support::{PromptSource, one_section, prompt};
@@ -11,7 +11,6 @@ use crate::execute::run::{EffectRecord, ToolCallOrigin, ToolCaller};
use crate::execute::scope::prepare_scoped_tools;
use crate::test_support::rig::Rig;
use crate::test_support::scenario::EXECUTION;
-use runvil_model_client::detail::tool_schema_new;
use runvil_types::packs::PackId;
/// A catalog tool under any id, described by its id, echoing its `value`
@@ -141,7 +140,7 @@ fn a_script_offers_the_extras_and_the_model_calls_an_offered_tool_by_its_wire_na
text("done"),
]);
let source = one_section(
- "tools.offer(tools.extras())\n\
+ "tools.offer(tools.packs.extras())\n\
messages:user('go')\n\
models.loop()\n\
return 'ok'",
@@ -173,7 +172,8 @@ fn a_script_offers_the_extras_and_the_model_calls_an_offered_tool_by_its_wire_na
}
/// Every key on a section's `tools` table, sorted, each with its Lua type.
-const TOOLS_TABLE_KEYS: &str = "call:function,extras:function,get:function,offer:function,offer_local:function,required:function";
+const TOOLS_TABLE_KEYS: &str =
+ "adhoc:function,call:function,get:function,offer:function,offer_dynamic:function,packs:table";
#[test]
fn a_section_tools_table_holds_only_its_api_and_its_round_advertises_only_the_offered_tool() {
@@ -182,7 +182,7 @@ fn a_section_tools_table_holds_only_its_api_and_its_round_advertises_only_the_of
"local keys = {}\n\
for key, value in pairs(tools) do keys[#keys + 1] = key .. ':' .. type(value) end\n\
table.sort(keys)\n\
- tools.offer(tools.extras())\n\
+ tools.offer(tools.packs.extras())\n\
messages:user('go')\n\
models.loop()\n\
return table.concat(keys, ',')",
@@ -211,7 +211,7 @@ fn a_section_tools_table_holds_only_its_api_and_its_round_advertises_only_the_of
#[test]
fn a_script_calls_an_offered_tool_by_its_object_and_by_its_id_without_offering_it() {
let source = one_section(
- "local tool = tools.extras()[1]\n\
+ "local tool = tools.packs.get('tools').tools[1]\n\
return tools.call(tool, { value = 'a' }) .. '|' .. \
tools.call('tools/echo', { value = 'b' }) .. '|' .. tool.id",
);
@@ -264,7 +264,7 @@ fn a_script_offers_a_declared_packs_tools_and_the_model_calls_one_by_its_wire_na
"uses: [tools]",
&[(
"Only",
- "tools.offer(packs.get('tools').tools)\n\
+ "tools.offer(tools.packs.get('tools').tools)\n\
messages:user('go')\n\
models.loop()\n\
return 'ok'",
@@ -293,8 +293,8 @@ fn a_script_offers_an_extra_packs_tools_after_checking_packs_get() {
text("done"),
]);
let source = one_section(
- "assert(packs.get('missing') == nil, 'an unknown Pack reads nil')\n\
- local gh = packs.get('gh')\n\
+ "assert(tools.packs.get('missing') == nil, 'an unknown Pack reads nil')\n\
+ local gh = tools.packs.get('gh')\n\
if gh then tools.offer(gh.tools) end\n\
messages:user('go')\n\
models.loop()\n\
@@ -317,12 +317,14 @@ fn a_script_offers_an_extra_packs_tools_after_checking_packs_get() {
}
#[test]
-fn the_packs_table_is_installed_in_the_h1_vm() {
+fn the_pack_objects_and_the_adhoc_pack_are_installed_in_the_h1_vm() {
let source = PromptSource::new()
.front("uses: [tools]")
.h1(
- "return packs.required()[1].name .. '|' .. packs.extras()[1].name .. '|' .. \
- tostring(tools.get('gh/search').pack == packs.get('gh'))",
+ "return tostring(tools.packs.get('tools').required) .. '|' .. \
+ tools.packs.extras()[1].name .. '|' .. \
+ tostring(tools.get('gh/search').pack == tools.packs.get('gh')) .. '|' .. \
+ #tools.packs.get('adhoc').tools",
)
.build();
let rig = Rig::run(
@@ -332,28 +334,40 @@ fn the_packs_table_is_installed_in_the_h1_vm() {
);
assert_eq!(
rig.trace().text(),
- "tools|gh|true",
- "the H1 pass reads the packs table"
+ "true|gh|true|0",
+ "the H1 pass reads the Pack objects, the empty adhoc Pack included"
);
}
#[test]
-fn a_round_leaves_out_an_offered_binding_a_local_tool_shares_a_name_with() {
- let offered = crate::lua::ToolBinding::from_info("tools_echo", &echo_tool().info());
- let local = tool_schema_new("tools_echo", "the local echo", json!({ "type": "object" }))
- .expect("the local schema is valid");
- let rendered = prepare_scoped_tools(&[offered], &[local]).expect("the round's scope builds");
- assert_eq!(
- rendered.schemas.len(),
- 1,
- "the model sees one tool under the name"
+fn a_rendered_list_maps_every_wire_name_to_its_id_and_an_adhoc_tool_to_no_vendor() {
+ let offered = crate::lua::ToolBinding::from_info("tools_echo", &echo_tool().info())
+ .with_vendor(Some("runvil".to_owned()));
+ let info = runvil_types::tools::ToolInfo::new(
+ ToolId::parse("adhoc/grab").expect("valid id"),
+ "Grab a value",
+ json!({ "type": "object", "properties": {}, "required": [] }),
);
- assert_eq!(rendered.schemas[0].description(), "the local echo");
- assert!(
- matches!(rendered.dispatch.get("tools_echo"), Some(None)),
- "the local tool answers the name: {:?}",
- rendered.dispatch
+ let adhoc = crate::lua::ToolBinding::from_info("grab", &info);
+ let rendered = prepare_scoped_tools(&[offered, adhoc]).expect("the round's scope builds");
+ let names: Vec<&str> = rendered
+ .schemas
+ .iter()
+ .map(crate::model::ToolSchema::name)
+ .collect();
+ assert_eq!(names, ["tools_echo", "grab"], "the bindings' order");
+ let entry = |name: &str| {
+ rendered
+ .dispatch
+ .get(name)
+ .map(|advertised| (advertised.id.to_string(), advertised.vendor.clone()))
+ };
+ assert_eq!(
+ entry("tools_echo"),
+ Some(("tools/echo".to_owned(), Some("runvil".to_owned())))
);
+ assert_eq!(entry("grab"), Some(("adhoc/grab".to_owned(), None)));
+ assert!(rendered.dynamic.is_empty());
}
#[path = "offering-packs.rs"]
diff --git a/crates/runvil-internal/engine/src/execute/tests/parallel_tool_calls.rs b/crates/runvil-internal/engine/src/execute/tests/parallel_tool_calls.rs
index 5406f7395..8cc6b902c 100644
--- a/crates/runvil-internal/engine/src/execute/tests/parallel_tool_calls.rs
+++ b/crates/runvil-internal/engine/src/execute/tests/parallel_tool_calls.rs
@@ -1,7 +1,7 @@
//! A round's catalog tool calls run in parallel: the loop sends every
//! unanswered call as one batch, the scheduler issues each catalog call in
//! the same step and answers once every issued call has landed, and the
-//! records append in call order. A local tool stops the batch and runs
+//! records append in call order. An adhoc tool stops the batch and runs
//! alone between its neighbors, a call that cannot be
//! bound stops it and raises once the issued calls land, and a task
//! cancelled while parked on a batch orphans every call in it and lists
@@ -145,12 +145,12 @@ fn a_rounds_catalog_calls_are_issued_in_one_step_and_append_in_call_order() {
}
#[test]
-fn local_calls_run_alone_between_their_neighbors() {
+fn adhoc_calls_run_alone_between_their_neighbors() {
let md = one_section(
"tools.offer('tools/echo')\n\
- tools.offer_local('grab', 'Local grab', { value = 'string' }, function(args)\n\
+ tools.offer(tools.adhoc({ name = 'grab', description = 'Local grab', parameters = { value = 'string' } }, function(args)\n\
return 'grabbed ' .. args.value\n\
- end)\n\
+ end))\n\
messages:user('use them all')\n\
models.loop()\n\
local ids = {}\n\
@@ -172,7 +172,7 @@ fn local_calls_run_alone_between_their_neighbors() {
assert_eq!(
call_value(&effect),
"a",
- "the batch stops before the local call"
+ "the batch stops before the adhoc call"
);
run.resume(first, tool_text("echoed a"));
let (last, effect) = only_effect(run.step());
@@ -199,7 +199,7 @@ fn local_calls_run_alone_between_their_neighbors() {
#[test]
fn a_call_the_round_cannot_bind_stops_the_batch_and_raises_once_the_issued_calls_land() {
let md = one_section(
- "packs.offer('tools')\n\
+ "tools.offer('tools')\n\
messages:user('asked')\n\
local ok, err = pcall(models.loop)\n\
return tostring(ok) .. ':' .. err.kind .. '|' .. #messages",
diff --git a/crates/runvil-internal/engine/src/execute/tests/rendered_tools.rs b/crates/runvil-internal/engine/src/execute/tests/rendered_tools.rs
index 2906a4311..ecfbbd19c 100644
--- a/crates/runvil-internal/engine/src/execute/tests/rendered_tools.rs
+++ b/crates/runvil-internal/engine/src/execute/tests/rendered_tools.rs
@@ -47,9 +47,9 @@ fn a_first_round_the_precheck_refuses_still_fixes_the_tool_list() {
messages:user(string.rep('x', 20000))
local ok, err = pcall(models.loop)
assert(not ok and err.reason == 'precheck', 'the narrow window refuses the round')
- local offered, refusal = pcall(tools.offer_local, 'grab', 'Local grab', {}, function()
+ local offered, refusal = pcall(tools.offer, tools.adhoc({ name = 'grab', description = 'Local grab' }, function()
return ''
- end)
+ end))
assert(not offered, 'the refused round fixed the list')
models.use('wide')
models.loop()
@@ -60,7 +60,7 @@ fn a_first_round_the_precheck_refuses_still_fixes_the_tool_list() {
.offer("echo", echo_tool())
.chat(&gateway)
.run();
- assert_eq!(trace.text(), format!("lua:tools.offer_local: {FIXED}"));
+ assert_eq!(trace.text(), format!("lua:tools.offer: {FIXED}"));
let bodies = gateway.requests();
assert_eq!(bodies.len(), 1, "only the round on the wide model left");
assert_eq!(
@@ -80,9 +80,9 @@ fn every_later_round_sends_the_same_tool_bytes_across_a_model_change() {
]);
let source = one_section(
"tools.offer('tools/echo')
- tools.offer_local('grab', 'Local grab', { value = 'string' }, function(args)
+ tools.offer(tools.adhoc({ name = 'grab', description = 'Local grab', parameters = { value = 'string' } }, function(args)
return 'grabbed ' .. args.value
- end)
+ end))
messages:user('one')
models.loop()
messages:user('two')
@@ -109,7 +109,7 @@ fn every_later_round_sends_the_same_tool_bytes_across_a_model_change() {
}
#[test]
-fn after_the_render_every_offer_function_raises_even_an_identical_one() {
+fn after_the_render_every_offer_raises_even_an_identical_one_while_defining_still_works() {
let gateway = ScriptedChat::new(vec![calls(&[("call_1", "grab", "{}")]), text("done")]);
let source = prompt(
"uses: [tools]",
@@ -117,23 +117,25 @@ fn after_the_render_every_offer_function_raises_even_an_identical_one() {
(
"Only",
"tools.offer('tools/echo')
- packs.offer('tools')
- tools.offer_local('grab', 'Local grab', {}, function()
+ tools.offer('tools')
+ tools.offer(tools.adhoc({ name = 'grab', description = 'Local grab' }, function()
local _, err = pcall(tools.offer, 'tools/echo')
return err.kind .. ':' .. tostring(err)
- end)
+ end))
messages:user('go')
models.loop()
local out = { messages[3].content }
for _, offer in ipairs({
function() tools.offer('tools/echo') end,
- function() packs.offer('tools') end,
- function() tools.offer_local('grab', 'Again', {}, function() return '' end) end,
+ function() tools.offer('tools') end,
+ function() tools.offer(tools.adhoc({ name = 'late', description = 'Late' }, function() return '' end)) end,
+ function() tools.offer_dynamic('tools') end,
function() require '## offers' end,
}) do
local _, err = pcall(offer)
out[#out + 1] = err.kind .. ':' .. tostring(err)
end
+ out[#out + 1] = tostring(tools.get('adhoc/late') ~= nil)
return table.concat(out, '\\n')",
),
("offers", "tools.offer('tools/echo')"),
@@ -146,27 +148,56 @@ fn after_the_render_every_offer_function_raises_even_an_identical_one() {
let lines: Vec<&str> = trace.text().lines().collect();
let offer = format!("lua:tools.offer: {FIXED}");
assert_eq!(
- lines[..4],
+ lines[..5],
[
offer.clone(),
offer.clone(),
- format!("lua:packs.offer: {FIXED}"),
- format!("lua:tools.offer_local: {FIXED}"),
+ offer.clone(),
+ offer.clone(),
+ format!("lua:tools.offer_dynamic: {FIXED}"),
],
"a handler's offer during the loop, then an identical re-offer of a tool \
- and of a Pack, and a repeated local alias"
+ and of a Pack, an offer of a tool defined after the render, and a \
+ dynamic offer"
);
- assert_eq!(lines.len(), 5, "{lines:?}");
+ assert_eq!(lines.len(), 7, "{lines:?}");
assert!(
- lines[4].contains(&format!("tools.offer: {FIXED}")),
+ lines[5].contains(&format!("tools.offer: {FIXED}")),
"an offer from a required library raises: {}",
- lines[4]
+ lines[5]
);
+ assert_eq!(lines[6], "true", "the tool defined after the render exists");
let bodies = gateway.requests();
assert_eq!(bodies[0].tool_names(), ["tools_echo", "grab"]);
assert_eq!(tool_bytes(&bodies)[0], tool_bytes(&bodies)[1]);
}
+#[test]
+fn dynamic_offers_leave_the_rendered_schemas_byte_for_byte_unchanged() {
+ let run = |dynamic: &str| {
+ let gateway = ScriptedChat::new(vec![text("done")]);
+ let source = one_section(&format!(
+ "{dynamic}tools.offer('tools/echo')
+ tools.offer(tools.adhoc({{ name = 'grab', description = 'Local grab' }}, function() return '' end))
+ messages:user('go')
+ models.loop()"
+ ));
+ loop_scenario(source)
+ .offer("echo", echo_tool())
+ .offer("shape", scalar_schema_tool())
+ .chat(&gateway)
+ .run();
+ tool_bytes(&gateway.requests())
+ };
+ let plain = run("");
+ assert_eq!(
+ run("tools.offer_dynamic('tools')\ntools.offer_dynamic(tools.packs)\n"),
+ plain,
+ "a dynamic offer, even of a tool no round could advertise, changes nothing \
+ the model sees"
+ );
+}
+
#[test]
fn a_first_round_refused_over_an_empty_list_renders_nothing() {
let gateway = ScriptedChat::new(vec![text("done")]);
@@ -241,7 +272,7 @@ fn a_first_round_whose_tool_build_fails_renders_nothing() {
local ok, err = pcall(models.loop)
assert(not ok, 'the scalar schema fails the build')
tools.offer('tools/echo')
- tools.offer_local('shape', 'Local shape', {}, function() return '' end)
+ tools.offer(tools.adhoc({ name = 'shape', description = 'Local shape' }, function() return '' end))
models.loop()
return err.kind .. ':' .. tostring(err)",
);
@@ -259,7 +290,7 @@ fn a_first_round_whose_tool_build_fails_renders_nothing() {
assert_eq!(
bodies[0].tool_names(),
["echo", "shape"],
- "both offers after the failed build reach the next round, the local \
+ "both offers after the failed build reach the next round, the adhoc \
tool in place of the unusable one"
);
}
diff --git a/crates/runvil-internal/engine/src/execute/tests/scheduler/failures-script-tools.rs b/crates/runvil-internal/engine/src/execute/tests/scheduler/failures-script-tools.rs
index ab95690a4..9381d977e 100644
--- a/crates/runvil-internal/engine/src/execute/tests/scheduler/failures-script-tools.rs
+++ b/crates/runvil-internal/engine/src/execute/tests/scheduler/failures-script-tools.rs
@@ -50,11 +50,11 @@ fn a_script_tools_call_with_an_unbound_name_lists_the_offered_ids() {
let md = "---\nname: t\ndescription: d\nrunvil: 0\n---\n\n\
# ToolCall\n\n\
## Only\n\n\
- ```lua\ntools.offer('tools/echo')\nreturn tools.call('missing', {})\n```\n";
+ ```lua\ntools.offer('tools/echo')\nreturn tools.call('tools/missing', {})\n```\n";
let trace = scheduler_scenario(md).offer("echo", echo_tool()).run();
match trace.error().inner() {
Error::UnboundToolCall { name, ids } => {
- assert_eq!(name, "missing");
+ assert_eq!(name, "tools/missing");
assert_eq!(ids, &["tools/echo".to_owned()]);
}
other => panic!("expected the typed unbound-tool error, got {other:?}"),
diff --git a/crates/runvil-internal/engine/src/execute/tests/scheduler/live_h1/control_flow.rs b/crates/runvil-internal/engine/src/execute/tests/scheduler/live_h1/control_flow.rs
index 2684d89d7..3ab84e97c 100644
--- a/crates/runvil-internal/engine/src/execute/tests/scheduler/live_h1/control_flow.rs
+++ b/crates/runvil-internal/engine/src/execute/tests/scheduler/live_h1/control_flow.rs
@@ -115,11 +115,11 @@ fn fanout_from_h1_runs_the_worker_over_the_collection() {
#[test]
fn the_h1_decision_tool_idiom_runs_before_the_walk() {
- // The decision-tool idiom in H1: a local tool with an enum parameter is
+ // The decision-tool idiom in H1: an adhoc tool with an enum parameter is
// the verdict channel - the model's loop call lands in the Lua handler,
// and the captured verdict drives the run's shape before the walk. This
- // needs `tools.offer_local` and `models.loop` in H1, both section-only
- // before the one-install-path consolidation.
+ // needs `tools.adhoc`, `tools.offer`, and `models.loop` in H1, which
+ // installs them on the one path every section takes.
let gateway = ScriptedChat::new(vec![
calls(&[("call_1", "decide", "{\"choice\":\"use_mcp\"}")]),
text("decided"),
@@ -128,10 +128,10 @@ fn the_h1_decision_tool_idiom_runs_before_the_walk() {
# Decide\n\n\
```lua\n\
models.default('writer')\n\
- tools.offer_local('decide', 'Record the verdict', { choice = 'string' }, function(args)\n\
+ tools.offer(tools.adhoc({ name = 'decide', description = 'Record the verdict', parameters = { choice = 'string' } }, function(args)\n\
var.verdict = args.choice\n\
return 'recorded'\n\
- end)\n\
+ end))\n\
messages:user('interpret the guidance')\n\
models.loop()\n\
```\n\n\
diff --git a/crates/runvil-internal/engine/src/execute/tests/section_messages.rs b/crates/runvil-internal/engine/src/execute/tests/section_messages.rs
index 615f53dfb..93d3a2d70 100644
--- a/crates/runvil-internal/engine/src/execute/tests/section_messages.rs
+++ b/crates/runvil-internal/engine/src/execute/tests/section_messages.rs
@@ -280,15 +280,15 @@ fn replace_and_compactors_clear_work_inside_an_overflow_compactor_and_inside_mod
fn meta_reaches_a_tool_through_a_view_but_never_the_model() {
let source = PromptSource::new().section(
"Only",
- "tools.offer_local('probe', 'Read a record', {}, function(args)
+ "tools.offer(tools.adhoc({ name = 'probe', description = 'Read a record' }, function(args)
return args.record.meta.hint
- end)
+ end))
messages:system('be terse', { hint = 'system' })
:user('look', { hint = 'user' })
:assistant('', { { id = 'call_1', name = 'probe' } }, { hint = 'assistant' })
:tool('probed', 'call_1', { hint = 'tool' })
:append({ role = 'user', content = 'go on', meta = { hint = 'append' } })
- local probed = tools.call('probe', { record = messages[5] })
+ local probed = tools.call('adhoc/probe', { record = messages[5] })
models.loop()
local last = messages[#messages]
return table.concat({ probed, #messages, last.content, tostring(last.meta) }, '|')",
@@ -319,7 +319,7 @@ fn both_loop_entries_take_only_a_compactor_and_check_it_before_a_running_loop()
local ok, err = pcall(call)
refusals[#refusals + 1] = tostring(ok) .. ':' .. err.kind .. ':' .. tostring(err)
end
- tools.offer_local('probe', 'Probe the loop entries', { value = 'string' }, function()
+ tools.offer(tools.adhoc({ name = 'probe', description = 'Probe the loop entries', parameters = { value = 'string' } }, function()
refuse(function() return models.loop(other) end)
refuse(function() return models.loop(nil, nil) end)
refuse(function() return models.loop(42) end)
@@ -329,7 +329,7 @@ fn both_loop_entries_take_only_a_compactor_and_check_it_before_a_running_loop()
refuse(function() return other:loop(42) end)
refuse(function() return other:loop(compactors.fail) end)
return 'probed'
- end)
+ end))
messages:user('probe the entries')
models.loop()
return table.concat(refusals, '\\n') .. '\\n' .. #messages",
diff --git a/crates/runvil-internal/engine/src/execute/tests/suite/exec_flow/run_setup.rs b/crates/runvil-internal/engine/src/execute/tests/suite/exec_flow/run_setup.rs
index ef1927c1a..b1d552bf1 100644
--- a/crates/runvil-internal/engine/src/execute/tests/suite/exec_flow/run_setup.rs
+++ b/crates/runvil-internal/engine/src/execute/tests/suite/exec_flow/run_setup.rs
@@ -114,7 +114,7 @@ fn offering_a_tool_its_present_pack_does_not_offer_fails_the_section() {
assert!(
error
.to_string()
- .contains("tools.offer: \"tools/search\" is not a catalog tool in this run"),
+ .contains("tools.offer: \"tools/search\" is not a tool in this run"),
"the failure names the id: {error}"
);
}
diff --git a/crates/runvil-internal/engine/src/execute/tests/tool_call_arm-local-handlers.rs b/crates/runvil-internal/engine/src/execute/tests/tool_call_arm-adhoc-handlers.rs
similarity index 52%
rename from crates/runvil-internal/engine/src/execute/tests/tool_call_arm-local-handlers.rs
rename to crates/runvil-internal/engine/src/execute/tests/tool_call_arm-adhoc-handlers.rs
index 28eba959e..0f5ba01b9 100644
--- a/crates/runvil-internal/engine/src/execute/tests/tool_call_arm-local-handlers.rs
+++ b/crates/runvil-internal/engine/src/execute/tests/tool_call_arm-adhoc-handlers.rs
@@ -1,26 +1,48 @@
-//! Local Lua tools: a handler runs inside the calling block coroutine
+//! Adhoc tools: a handler runs inside the calling block coroutine
//! with no leaf work of its own and reports its trusted result under
//! the model's call id or none; it uses the store, raises to a script
-//! caller that catches it, calls another local tool innermost first,
+//! caller that catches it, calls another adhoc tool innermost first,
//! and dispatches a bound tool as one leaf request, whose failure
//! raises kind `tool` in the handler and whose untrusted wrapper
-//! survives.
+//! survives. A model-issued call routes by the section's rendered list,
+//! so those cases run one loop round first.
use runvil_parser::test_support::prompt;
use super::*;
use crate::execute::tests::fixtures::{echo_tool, failing_tool, untrusted_echo_tool};
-/// The `grab` local tool registration every local-tool test opens with.
-const ADD_LOCAL_GRAB: &str = "tools.offer_local('grab', 'Grab a value', { value = 'string' }, \
- function(args) return 'got ' .. args.value end)\n";
+/// The `grab` adhoc tool definition every adhoc-tool test opens with,
+/// offered to the section.
+const ADD_ADHOC_GRAB: &str = "tools.offer(tools.adhoc({ name = 'grab', description = 'Grab a \
+ value', parameters = { value = 'string' } }, function(args) return 'got ' .. args.value \
+ end))\n";
+
+/// One loop round the model answers with text, which renders the
+/// section's tool list so a model-issued call can route by it.
+const RENDER: &str = "messages:user('go')\nmodels.loop()\n";
+
+/// The arm scenario over `source` with one text round for [`RENDER`].
+fn rendered_scenario(source: impl Into) -> (Scenario, ScriptedChat) {
+ let gateway = ScriptedChat::new(vec![text("rendered")]);
+ (arm_scenario(source), gateway)
+}
+
+/// How many tool-call effects `trace` issued.
+fn tool_call_effects(trace: &Trace) -> usize {
+ trace
+ .effects()
+ .iter()
+ .filter(|(effect, _)| matches!(effect, EffectRecord::ToolCall { .. }))
+ .count()
+}
#[test]
-fn a_local_lua_tool_call_issues_no_leaf_work() {
+fn an_adhoc_tool_call_issues_no_leaf_work() {
let source = one_section(&format!(
- "{ADD_LOCAL_GRAB}\
- local out = tools.call('grab', {{ value = 'hi' }})\n\
- return out .. '|' .. tostring(tools.calls.grab)"
+ "{ADD_ADHOC_GRAB}\
+ local out = tools.call('adhoc/grab', {{ value = 'hi' }})\n\
+ return out .. '|' .. tostring(tools.calls['adhoc/grab'])"
));
let trace = arm_scenario(source).run();
assert_eq!(
@@ -31,35 +53,57 @@ fn a_local_lua_tool_call_issues_no_leaf_work() {
assert_eq!(
trace.effects().len(),
0,
- "a local tool call spawns no leaf request"
+ "an adhoc tool call spawns no leaf request"
);
let lines = tool_lines(&trace).lines();
assert!(
lines
.iter()
.any(|line| line == &format!("Only: {}", detail::TOOL_CALL_SUCCEEDED)),
- "the local call is observed as a succeeded tool call: {lines:?}"
+ "the adhoc call is observed as a succeeded tool call: {lines:?}"
);
assert!(
lines
.iter()
.any(|line| line == "Only: tool_result id= alias=grab trust=Trusted content=got hi"),
- "a script-initiated local call reports its trusted result under no call id: {lines:?}"
+ "a script-initiated adhoc call reports its trusted result under no call id: {lines:?}"
);
}
#[test]
-fn a_model_issued_local_tool_call_reports_under_its_call_id() {
- let source = one_section(&format!(
- "{ADD_LOCAL_GRAB}\
+fn a_script_calls_an_unoffered_adhoc_tool_by_id_or_object_before_and_after_the_render() {
+ let (scenario, gateway) = rendered_scenario(one_section(&format!(
+ "local grab = tools.adhoc({{ name = 'grab', description = 'Grab a value', \
+ parameters = {{ value = 'string' }} }}, function(args) return 'got ' .. args.value end)\n\
+ local before = tools.call(grab, {{ value = 'a' }})\n\
+ {RENDER}\
+ local after = tools.call('adhoc/grab', {{ value = 'b' }})\n\
+ return before .. '|' .. after .. '|' .. tostring(tools.calls['adhoc/grab'])"
+ )));
+ let trace = scenario.chat(&gateway).run();
+ assert_eq!(
+ trace.text(),
+ "got a|got b|2",
+ "an adhoc tool needs no offer to be called, and the render leaves it callable"
+ );
+ assert!(
+ gateway.requests()[0].tools.is_empty(),
+ "an unoffered adhoc tool is never rendered"
+ );
+}
+
+#[test]
+fn a_model_issued_adhoc_tool_call_reports_under_its_call_id() {
+ let (scenario, gateway) = rendered_scenario(one_section(&format!(
+ "{ADD_ADHOC_GRAB}{RENDER}\
return tools.call_as_model('call_7', 'grab', {{ value = 'hi' }})"
- ));
- let trace = arm_scenario(source).run();
+ )));
+ let trace = scenario.chat(&gateway).run();
assert_eq!(trace.text(), "got hi");
assert_eq!(
- trace.effects().len(),
+ tool_call_effects(&trace),
0,
- "a model-issued local call spawns no leaf request"
+ "a model-issued adhoc call spawns no leaf request"
);
let lines = tool_lines(&trace).lines();
assert!(
@@ -72,13 +116,13 @@ fn a_model_issued_local_tool_call_reports_under_its_call_id() {
}
#[test]
-fn a_script_called_local_handler_uses_the_store() {
+fn a_script_called_adhoc_handler_uses_the_store() {
let source = one_section(
- "tools.offer_local('grab', 'Grab a value', { value = 'string' }, function(args)
+ "tools.offer(tools.adhoc({ name = 'grab', description = 'Grab a value', parameters = { value = 'string' } }, function(args)
store.write('grab.txt', 'kept ' .. args.value)
return store.read('grab.txt')
- end)
- return tools.call('grab', { value = 'hi' })",
+ end))
+ return tools.call('adhoc/grab', { value = 'hi' })",
);
let trace = arm_scenario(source).run();
assert_eq!(trace.text(), "kept hi");
@@ -91,8 +135,8 @@ fn a_script_called_local_handler_uses_the_store() {
#[test]
fn a_script_caller_catches_the_handlers_own_error_and_jump_is_restored() {
let only = "local raised = { kind = 'custom', message = 'handler exploded' }
- tools.offer_local('grab', 'Grab a value', {}, function() error(raised) end)
- local ok, err = pcall(tools.call, 'grab', {})
+ tools.offer(tools.adhoc({ name = 'grab', description = 'Grab a value' }, function() error(raised) end))
+ local ok, err = pcall(tools.call, 'adhoc/grab', {})
assert(not ok, 'the handler raise reaches the call site')
assert(err == raised and err.kind == 'custom', 'the caller catches the handler table')
jump('## Other')";
@@ -117,17 +161,17 @@ fn a_script_caller_catches_the_handlers_own_error_and_jump_is_restored() {
}
#[test]
-fn a_nested_local_call_reports_both_results_innermost_first() {
- let source = one_section(
- "tools.offer_local('inner', 'Inner', { value = 'string' }, function(args)
+fn a_nested_adhoc_call_reports_both_results_innermost_first() {
+ let (scenario, gateway) = rendered_scenario(one_section(&format!(
+ "tools.offer(tools.adhoc({{ name = 'inner', description = 'Inner', parameters = {{ value = 'string' }} }}, function(args)
return 'inner ' .. args.value
- end)
- tools.offer_local('outer', 'Outer', { value = 'string' }, function(args)
- return 'outer ' .. tools.call('inner', { value = args.value })
- end)
- return tools.call_as_model('call_1', 'outer', { value = 'hi' })",
- );
- let trace = arm_scenario(source).run();
+ end))
+ tools.offer(tools.adhoc({{ name = 'outer', description = 'Outer', parameters = {{ value = 'string' }} }}, function(args)
+ return 'outer ' .. tools.call('adhoc/inner', {{ value = args.value }})
+ end))
+ {RENDER}return tools.call_as_model('call_1', 'outer', {{ value = 'hi' }})",
+ )));
+ let trace = scenario.chat(&gateway).run();
assert_eq!(trace.text(), "outer inner hi");
assert_eq!(
tool_result_lines(&tool_lines(&trace)),
@@ -144,33 +188,33 @@ fn a_nested_local_call_reports_both_results_innermost_first() {
fn a_handler_dispatches_a_bound_tool_as_one_leaf_request() {
let source = one_section(
"tools.offer('tools/echo')
- tools.offer_local('grab', 'Grab a value', { value = 'string' }, function(args)
+ tools.offer(tools.adhoc({ name = 'grab', description = 'Grab a value', parameters = { value = 'string' } }, function(args)
return tools.call('tools/echo', { value = args.value })
- end)
- local out = tools.call('grab', { value = 'hi' })
- return out .. '|' .. tostring(tools.calls.grab) .. '|' .. tostring(tools.calls['tools/echo'])",
+ end))
+ local out = tools.call('adhoc/grab', { value = 'hi' })
+ return out .. '|' .. tostring(tools.calls['adhoc/grab']) .. '|' .. tostring(tools.calls['tools/echo'])",
);
let trace = arm_scenario(source).offer("echo", echo_tool()).run();
assert_eq!(trace.text(), "echoed: hi|1|1", "both calls count once");
assert_eq!(
trace.effects().len(),
1,
- "the echo call is the one leaf request; the local call issues none"
+ "the echo call is the one leaf request; the adhoc call issues none"
);
}
#[test]
-fn a_bound_failure_inside_a_model_issued_local_call_raises_kind_tool_in_the_handler() {
- let source = one_section(
+fn a_bound_failure_inside_a_model_issued_adhoc_call_raises_kind_tool_in_the_handler() {
+ let (scenario, gateway) = rendered_scenario(one_section(&format!(
"tools.offer('tools/failing')
- tools.offer_local('grab', 'Grab a value', {}, function()
- local ok, err = pcall(tools.call, 'tools/failing', {})
+ tools.offer(tools.adhoc({{ name = 'grab', description = 'Grab a value' }}, function()
+ local ok, err = pcall(tools.call, 'tools/failing', {{}})
assert(not ok, 'the bound failure raises inside the handler')
return err.kind
- end)
- return tools.call_as_model('call_1', 'grab', {})",
- );
- let trace = arm_scenario(source).offer("fail", failing_tool()).run();
+ end))
+ {RENDER}return tools.call_as_model('call_1', 'grab', {{}})",
+ )));
+ let trace = scenario.offer("fail", failing_tool()).chat(&gateway).run();
assert_eq!(
trace.text(),
"tool",
@@ -179,7 +223,7 @@ fn a_bound_failure_inside_a_model_issued_local_call_raises_kind_tool_in_the_hand
assert_eq!(
tool_result_lines(&tool_lines(&trace)),
vec!["Only: tool_result id=call_1 alias=grab trust=Trusted content=tool".to_owned()],
- "the inner failure fires no ToolResult; only the local call reports under call_1"
+ "the inner failure fires no ToolResult; only the adhoc call reports under call_1"
);
}
@@ -187,11 +231,11 @@ fn a_bound_failure_inside_a_model_issued_local_call_raises_kind_tool_in_the_hand
fn a_handlers_text_stays_trusted_and_a_bound_tools_wrapper_survives() {
let source = one_section(
"tools.offer('tools/untrusted_echo')
- tools.offer_local('plain', 'Plain', {}, function() return 'plain text' end)
- tools.offer_local('grab', 'Grab a value', { value = 'string' }, function(args)
+ tools.offer(tools.adhoc({ name = 'plain', description = 'Plain' }, function() return 'plain text' end))
+ tools.offer(tools.adhoc({ name = 'grab', description = 'Grab a value', parameters = { value = 'string' } }, function(args)
return tools.call('tools/untrusted_echo', { value = args.value })
- end)
- return tools.call('plain', {}) .. '||' .. tools.call('grab', { value = 'hi' })",
+ end))
+ return tools.call('adhoc/plain', {}) .. '||' .. tools.call('adhoc/grab', { value = 'hi' })",
);
let trace = arm_scenario(source)
.offer("echo", untrusted_echo_tool())
diff --git a/crates/runvil-internal/engine/src/execute/tests/tool_call_arm.rs b/crates/runvil-internal/engine/src/execute/tests/tool_call_arm.rs
index 5a4389459..1d269466f 100644
--- a/crates/runvil-internal/engine/src/execute/tests/tool_call_arm.rs
+++ b/crates/runvil-internal/engine/src/execute/tests/tool_call_arm.rs
@@ -1,15 +1,15 @@
//! Tests for the scheduler's `tool_call` arm: the model-issued form
//! (`call_id: Some`), which always resumes with content and reports its
//! `ToolResult` under the model's call id; the script form (`call_id:
-//! None`), which keeps the raise-at-call-site behavior; local Lua tools,
+//! None`), which keeps the raise-at-call-site behavior; adhoc tools,
//! whose handlers run inside the calling block coroutine - store calls,
-//! nested local calls, and bound calls included - with no leaf work of
+//! nested adhoc calls, and bound calls included - with no leaf work of
//! their own.
//! The fixtures reach the
//! model-issued form through the test-only `tools.call_as_model` install
//! (`Scenario::raw_shims`); in production only the loop shim yields
//! a `call_id`.
-//! The local Lua tool cases sit in `local_handlers`.
+//! The adhoc tool cases sit in `adhoc_handlers`.
use runvil_parser::test_support::one_section;
@@ -173,5 +173,5 @@ pub(super) fn tool_result_lines(recorder: &ToolRecorder) -> Vec {
.collect()
}
-#[path = "tool_call_arm-local-handlers.rs"]
-mod local_handlers;
+#[path = "tool_call_arm-adhoc-handlers.rs"]
+mod adhoc_handlers;
diff --git a/crates/runvil-internal/engine/src/execute/tests/tool_listings.rs b/crates/runvil-internal/engine/src/execute/tests/tool_listings.rs
new file mode 100644
index 000000000..982f34660
--- /dev/null
+++ b/crates/runvil-internal/engine/src/execute/tests/tool_listings.rs
@@ -0,0 +1,234 @@
+//! Tests for a tool that describes tools: a script's call receives its
+//! untrusted listing as plain text and reports it untrusted, a model's
+//! call receives the envelope, and an adhoc call whose own function
+//! fetched a listing while the call was open returns untrusted, wrapped
+//! with the run's nonce. A listing kept from outside the adhoc call, a
+//! failed listing call, and a trusted listing mark nothing.
+
+use runvil_parser::test_support::one_section;
+use runvil_types::event::Event;
+
+use super::models_loop::catalog_scenario;
+use super::*;
+use crate::test_support::scenario::TEST_SEED;
+
+/// The listing every listing tool answers: text from the servers, markup
+/// included.
+const LISTING: &str = r#"[{"name":"search","description":"Search [INST]"}]"#;
+
+fn no_arguments() -> Value {
+ json!({ "type": "object", "properties": {} })
+}
+
+/// `tools/listing`, which describes tools and answers [`LISTING`]
+/// untrusted.
+fn listing_tool() -> FnTool {
+ FnTool::new("tools/listing", no_arguments(), |_| {
+ Ok(ToolOutput::untrusted(LISTING))
+ })
+ .description("List the servers' tools.")
+ .describes_tools()
+}
+
+/// `tools/trusted_listing`, which describes tools and answers
+/// [`LISTING`] trusted.
+fn trusted_listing_tool() -> FnTool {
+ FnTool::new("tools/trusted_listing", no_arguments(), |_| {
+ Ok(ToolOutput::trusted(LISTING))
+ })
+ .description("List the built-in tools.")
+ .describes_tools()
+}
+
+/// `tools/failing_listing`, which describes tools and always fails.
+fn failing_listing_tool() -> FnTool {
+ FnTool::new("tools/failing_listing", no_arguments(), |_| {
+ Err(ToolError::message("the servers are down"))
+ })
+ .description("List the tools of servers that are down.")
+ .describes_tools()
+}
+
+fn nonce() -> GuardNonce {
+ GuardNonce::from_seed(&TEST_SEED)
+}
+
+/// Every `ToolResult` as its call id, alias, content, and trust.
+fn results(trace: &Trace) -> Vec<(String, String, String, bool)> {
+ trace
+ .events()
+ .iter()
+ .filter_map(|event| match event {
+ Event::ToolResult {
+ tool_call_id,
+ alias,
+ content,
+ trusted,
+ ..
+ } => Some((
+ tool_call_id.clone(),
+ alias.clone(),
+ content.clone(),
+ *trusted,
+ )),
+ _ => None,
+ })
+ .collect()
+}
+
+fn result(id: &str, alias: &str, content: &str, trusted: bool) -> (String, String, String, bool) {
+ (id.to_owned(), alias.to_owned(), content.to_owned(), trusted)
+}
+
+/// The content of every `tool` turn the last round sent the model.
+fn tool_turns(bodies: &[ScriptedCall]) -> Vec {
+ bodies
+ .last()
+ .expect("the loop sends a closing round")
+ .messages_json()
+ .as_array()
+ .expect("a round's messages serialize to an array")
+ .iter()
+ .filter(|message| message["role"] == Role::Tool.as_str())
+ .filter_map(|message| message["content"].as_str().map(str::to_owned))
+ .collect()
+}
+
+/// The run of a section whose loop the model answers with `requested`,
+/// one round each, then a closing text, over every listing tool and
+/// `tools/untrusted_echo`.
+fn looped(section: &str, requested: &[&[(&str, &str, &str)]]) -> (Trace, ScriptedChat) {
+ let mut replies: Vec<_> = requested.iter().map(|batch| calls(batch)).collect();
+ replies.push(text("done"));
+ let gateway = ScriptedChat::new(replies);
+ let trace = catalog_scenario(one_section(&format!(
+ "{section}\n\
+ messages:user('list the tools')\n\
+ models.loop()\n\
+ return 'ok'"
+ )))
+ .tool(listing_tool())
+ .tool(trusted_listing_tool())
+ .tool(failing_listing_tool())
+ .tool(untrusted_echo_tool())
+ .chat(&gateway)
+ .run();
+ assert_eq!(trace.text(), "ok");
+ (trace, gateway)
+}
+
+#[test]
+fn a_scripts_listing_call_returns_the_text_unwrapped_and_reports_it_untrusted() {
+ let trace = catalog_scenario(one_section("return tools.call('tools/listing', {})"))
+ .tool(listing_tool())
+ .run();
+ assert_eq!(
+ trace.text(),
+ LISTING,
+ "the script reads the listing as written"
+ );
+ assert_eq!(
+ results(&trace),
+ [result("", "tools_listing", LISTING, false)],
+ "the result event holds the text the script received, untrusted"
+ );
+}
+
+#[test]
+fn a_script_call_to_a_tool_without_the_flag_stays_wrapped() {
+ let trace = catalog_scenario(one_section(
+ "return tools.call('tools/untrusted_echo', { value = 'hi' })",
+ ))
+ .tool(untrusted_echo_tool())
+ .run();
+ assert_eq!(trace.text(), nonce().wrap("echoed: hi"));
+}
+
+#[test]
+fn a_model_call_and_a_model_call_to_an_adhoc_wrapper_receive_the_same_envelope() {
+ let (trace, gateway) = looped(
+ "tools.offer('tools/listing')
+ tools.offer(tools.adhoc({ name = 'wrap', description = 'List the tools' }, function()
+ return tools.call('tools/listing', {})
+ end))",
+ &[&[("call_1", "tools_listing", "{}"), ("call_2", "wrap", "{}")]],
+ );
+ let envelope = nonce().wrap(LISTING);
+ assert_eq!(
+ tool_turns(&gateway.requests()),
+ [envelope.clone(), envelope.clone()],
+ "the direct call and the wrapper hand the model one envelope, byte for byte"
+ );
+ let results = results(&trace);
+ for expected in [
+ result("call_1", "tools_listing", &envelope, false),
+ result("", "tools_listing", LISTING, false),
+ result("call_2", "wrap", &envelope, false),
+ ] {
+ assert!(results.contains(&expected), "{expected:?} in {results:?}");
+ }
+}
+
+#[test]
+fn an_adhoc_function_returning_its_own_text_around_a_listing_returns_untrusted() {
+ let (trace, gateway) = looped(
+ "tools.offer(tools.adhoc({ name = 'wrap', description = 'List the tools' }, function()
+ return 'tools: ' .. tools.call('tools/listing', {})
+ end))",
+ &[&[("call_1", "wrap", "{}")]],
+ );
+ let envelope = nonce().wrap(&format!("tools: {LISTING}"));
+ assert_eq!(
+ tool_turns(&gateway.requests()),
+ std::slice::from_ref(&envelope)
+ );
+ assert!(
+ results(&trace).contains(&result("call_1", "wrap", &envelope, false)),
+ "{:?}",
+ results(&trace)
+ );
+}
+
+#[test]
+fn a_listing_kept_from_outside_the_adhoc_call_comes_back_unwrapped_and_trusted() {
+ let (trace, gateway) = looped(
+ "local kept = tools.call('tools/listing', {})
+ tools.offer(tools.adhoc({ name = 'kept', description = 'The kept listing' }, function() return kept end))",
+ &[&[("call_1", "kept", "{}")]],
+ );
+ assert_eq!(tool_turns(&gateway.requests()), [LISTING.to_owned()]);
+ assert!(
+ results(&trace).contains(&result("call_1", "kept", LISTING, true)),
+ "{:?}",
+ results(&trace)
+ );
+}
+
+#[test]
+fn a_failed_listing_call_and_a_trusted_listing_mark_nothing() {
+ let (trace, gateway) = looped(
+ "tools.offer(tools.adhoc({ name = 'failed', description = 'A failed listing' }, function()
+ local ok = pcall(tools.call, 'tools/failing_listing', {})
+ return 'listed ' .. tostring(ok)
+ end))
+ tools.offer(tools.adhoc({ name = 'trusted', description = 'A trusted listing' }, function()
+ return tools.call('tools/trusted_listing', {})
+ end))",
+ &[
+ &[("call_1", "failed", "{}")],
+ &[("call_2", "trusted", "{}")],
+ ],
+ );
+ assert_eq!(
+ tool_turns(&gateway.requests()),
+ ["listed false".to_owned(), LISTING.to_owned()]
+ );
+ let results = results(&trace);
+ for expected in [
+ result("call_1", "failed", "listed false", true),
+ result("", "tools_trusted_listing", LISTING, true),
+ result("call_2", "trusted", LISTING, true),
+ ] {
+ assert!(results.contains(&expected), "{expected:?} in {results:?}");
+ }
+}
diff --git a/crates/runvil-internal/engine/src/execute/tests/tool_scoping.rs b/crates/runvil-internal/engine/src/execute/tests/tool_scoping.rs
index 622058c75..914232d63 100644
--- a/crates/runvil-internal/engine/src/execute/tests/tool_scoping.rs
+++ b/crates/runvil-internal/engine/src/execute/tests/tool_scoping.rs
@@ -7,6 +7,7 @@ use super::models_loop::{LOOP_TO_TEXT, loop_scenario};
use super::*;
use crate::lua::{ToolBinding, ToolSet};
use crate::test_support::scenario::TEST_SEED;
+use runvil_lua::{AdhocTools, OfferMode};
/// The tool set offering `tool` under the wire name `alias`, described as
/// `description`, for a test that reads the offering without a run.
@@ -27,7 +28,8 @@ fn offered_tools_are_not_injected_without_an_offer() {
let (tool, _) = scoped_tool("concrete", "Concrete description.");
let tools = offering_of("tools_concrete", "capability", &tool);
let runtime = Mutex::new(runvil_lua::ToolRuntime::default());
- let effective = current_tool_bindings(&tools, &runtime).expect("the scope must snapshot");
+ let effective = current_tool_bindings(&tools, &runtime, &AdhocTools::default())
+ .expect("the scope must snapshot");
assert!(
effective.is_empty(),
"an offering must not expose a tool without an explicit offer"
@@ -42,12 +44,14 @@ fn an_offered_tool_advertises_its_concrete_schema_under_its_wire_name_and_dispat
]);
let (tool, called) = scoped_tool("concrete", "Concrete description.");
let tools = offering_of("tools_concrete", "Concrete description.", &tool);
- let runtime = Mutex::new(runvil_lua::ToolRuntime {
- added: vec!["tools_concrete".to_owned()],
- ..runvil_lua::ToolRuntime::default()
- });
- let effective = current_tool_bindings(&tools, &runtime).expect("the offered scope snapshots");
- let schemas = prepare_scoped_tools(&effective, &[])
+ let mut runtime = runvil_lua::ToolRuntime::default();
+ runtime.add_tool(
+ ToolId::parse("tools/concrete").expect("a fixture tool id"),
+ OfferMode::Static,
+ );
+ let effective = current_tool_bindings(&tools, &Mutex::new(runtime), &AdhocTools::default())
+ .expect("the offered scope snapshots");
+ let schemas = prepare_scoped_tools(&effective)
.expect("schemas must build")
.schemas;
assert_eq!(schemas.len(), 1);
@@ -108,9 +112,9 @@ fn a_section_offer_by_id_scopes_the_tool_and_dispatches_it() {
vm.run_chunk(&offer, &null_emitter(), "Only")
.expect("tools.offer must succeed");
let (tool_bindings, tool_runtime) = vm.tool_bag_handles();
- let scope =
- current_tool_bindings(&tool_bindings, &tool_runtime).expect("tool scope must snapshot");
- let schemas = prepare_scoped_tools(&scope, &[])
+ let scope = current_tool_bindings(&tool_bindings, &tool_runtime, vm.adhoc_tools())
+ .expect("tool scope must snapshot");
+ let schemas = prepare_scoped_tools(&scope)
.expect("schemas must build")
.schemas;
assert_eq!(schemas.len(), 1);
diff --git a/crates/runvil-internal/engine/src/lib.rs b/crates/runvil-internal/engine/src/lib.rs
index 170a01aeb..f9edc5593 100644
--- a/crates/runvil-internal/engine/src/lib.rs
+++ b/crates/runvil-internal/engine/src/lib.rs
@@ -37,5 +37,5 @@ pub use crate::execute::{
AnswerRecord, ChatAnswerRecord, Effect, EffectAnswer, EffectId, EffectRecord, FailureRecord,
MissingService, ModelBindings, RequirementCheck, Requirements, Round, Run, RunContext,
RunError, RunErrorKind, RunLimits, RunResult, SourceLocation, Step, ToolAnswerRecord,
- ToolCallOrigin, ToolCaller, UnavailablePack, UnmetRequirement, perform_vfs_op,
+ ToolCallOrigin, ToolCaller, UnavailablePack, UnmetRequirement, UsablePack, perform_vfs_op,
};
diff --git a/crates/runvil-internal/engine/src/lua.rs b/crates/runvil-internal/engine/src/lua.rs
index 56aeee79d..76bfe7358 100644
--- a/crates/runvil-internal/engine/src/lua.rs
+++ b/crates/runvil-internal/engine/src/lua.rs
@@ -15,12 +15,13 @@
// a caller answers a `Vfs` effect through, and the
// model-facing message renderers a store failure carries.
pub(crate) use runvil_lua::{
- Argv, CoroStep, Library, LibraryBlock, LibraryKey, LuaBlockResult, MessageList, ModelReport,
- NonEmpty, OverflowReason, ProseState, QuotaResource, RenderedTools, ScriptReport, SectionText,
- SectionVm, ToolBinding, ToolCallCounts, ToolSet, Uninjected, UsageAnchor,
- current_tool_bindings, enrich_sys_model, exhaustion_detail, install_preludes,
- install_section_loop_shim, install_store_shims, install_ui, output_reserve, precheck,
- prepare_dispatch, prepare_model_dispatch, project_messages, render_item, resolve_model_binding,
+ Advertised, Argv, CoroStep, Library, LibraryBlock, LibraryKey, LuaBlockResult, MessageList,
+ ModelReport, NonEmpty, OverflowReason, ProseState, QuotaResource, RenderedTools, ScriptReport,
+ SectionText, SectionVm, ToolBinding, ToolCallCounts, ToolSet, Uninjected, UsageAnchor,
+ current_dynamic_tools, current_tool_bindings, enrich_sys_model, exhaustion_detail,
+ install_preludes, install_section_loop_shim, install_store_shims, install_ui, output_reserve,
+ precheck, prepare_dispatch, prepare_model_dispatch, project_messages, render_item,
+ resolve_model_binding,
};
pub(crate) use runvil_lua::{run_store_op, store_error_message, store_probe_message};
diff --git a/crates/runvil-internal/engine/src/lua/tests/shims.rs b/crates/runvil-internal/engine/src/lua/tests/shims.rs
index 02130f0cd..80852c82b 100644
--- a/crates/runvil-internal/engine/src/lua/tests/shims.rs
+++ b/crates/runvil-internal/engine/src/lua/tests/shims.rs
@@ -1,6 +1,6 @@
//! The yield shims installed on a scheduler-mode section VM produce
//! well-formed protocol requests: `models.infer`, `call`, `tasks.fanout`, and
-//! `tools.call` in their id and tool-object forms, the local tool
+//! `tools.call` in their id and tool-object forms, the adhoc tool
//! handshake, the loop's batch and its requesting turn, a model handle's
//! `infer` method, and the `infer` and `loop` methods a model handle
//! carries.
@@ -9,7 +9,7 @@ use runvil_types::metrics::ToolCallEvent;
use serde_json::json;
use crate::execute::protocol::{
- Answer, ChatOutcome, ChatResult, LocalToolOutcome, Request, SpawnVia, ToolCallOutcome, VfsOp,
+ AdhocToolOutcome, Answer, ChatOutcome, ChatResult, Request, SpawnVia, ToolCallOutcome, VfsOp,
VfsOutcome, YieldParse,
};
use crate::model::ModelSet;
@@ -181,29 +181,29 @@ fn tools_call_yields_a_well_formed_request() {
}
#[test]
-fn a_local_tool_handler_runs_inside_the_block_coroutine() {
+fn an_adhoc_tool_handler_runs_inside_the_block_coroutine() {
// The two-yield handshake end to end: the `tool_call` yield, the
- // `Local` answer handing over the handler, the handler's own `store`
- // yield from inside the same coroutine, the `local_tool_done` yield
+ // `Adhoc` answer handing over the handler, the handler's own `store`
+ // yield from inside the same coroutine, the `adhoc_tool_done` yield
// carrying its return, and the block's return with the answered text.
// `jump` is refused while the handler runs and back afterward.
let vm = scheduler_vm(&ModelSet::default(), None);
let (thread, yielded) = start(
&vm,
"local withheld\n\
- tools.offer_local('grab', 'Grab a value', { value = 'string' }, function(args)\n\
+ tools.offer(tools.adhoc({ name = 'grab', description = 'Grab a value', parameters = { value = 'string' } }, function(args)\n\
local ok, err = pcall(jump, '## Other')\n\
withheld = not ok\n\
- and tostring(err):find('jump is unavailable inside a local tool handler', 1, true) ~= nil\n\
+ and tostring(err):find('jump is unavailable inside an adhoc tool handler', 1, true) ~= nil\n\
store.write('grab.txt', args.value)\n\
return 'stored ' .. args.value\n\
- end)\n\
- local out = tools.call('grab', { value = 'hi' })\n\
+ end))\n\
+ local out = tools.call('adhoc/grab', { value = 'hi' })\n\
return out .. '|' .. tostring(withheld) .. '|' .. tostring(jump ~= nil)",
);
match parse_request(&vm, yielded) {
Request::ToolCall { alias, call_id, .. } => {
- assert_eq!(alias, "grab");
+ assert_eq!(alias, "adhoc/grab");
assert_eq!(call_id, None);
}
other => panic!("the block's first yield is the tool call, got {other:?}"),
@@ -211,7 +211,7 @@ fn a_local_tool_handler_runs_inside_the_block_coroutine() {
let yielded = resume_with(
&vm,
&thread,
- Answer::ToolCallResult(Ok(ToolCallOutcome::Local {
+ Answer::ToolCallResult(Ok(ToolCallOutcome::Adhoc {
alias: "grab".to_owned(),
args: json!({ "value": "hi" }),
})),
@@ -227,8 +227,8 @@ fn a_local_tool_handler_runs_inside_the_block_coroutine() {
}
let yielded = resume_with(&vm, &thread, Answer::Store(Ok(VfsOutcome::Unit)));
match parse_request(&vm, yielded) {
- Request::LocalToolDone {
- outcome: LocalToolOutcome::Returned(text),
+ Request::AdhocToolDone {
+ outcome: AdhocToolOutcome::Returned(text),
} => assert_eq!(text, "stored hi"),
other => panic!("the handler's return is reported, got {other:?}"),
}
@@ -315,9 +315,9 @@ fn tools_call_accepts_a_tool_object_in_place_of_the_id() {
#[test]
fn tools_call_rejects_a_first_argument_that_is_neither_a_string_nor_a_tool() {
- // The polymorphism is a string (a tool id or a local alias) or a tool
- // object; anything else is the call's own error at the protocol
- // boundary, so an author pcall catches it at the call site.
+ // The polymorphism is a tool id or a tool object; anything else is the
+ // call's own error at the protocol boundary, so an author pcall
+ // catches it at the call site.
let vm = scheduler_vm(&ModelSet::default(), None);
let (_thread, yielded) = start(&vm, "return tools.call(42, {})");
let value = yielded.into_iter().next().expect("one yielded value");
@@ -325,7 +325,7 @@ fn tools_call_rejects_a_first_argument_that_is_neither_a_string_nor_a_tool() {
YieldParse::Call(answer) => {
let message = format!("{answer:?}");
assert!(
- message.contains("tools.call takes a tool id, a local alias, or a tool object"),
+ message.contains("tools.call takes a tool id or a tool object, got integer"),
"the rejection names the expected forms: {message}"
);
}
diff --git a/crates/runvil-internal/engine/src/test_support/recording/forward-tests-variants.rs b/crates/runvil-internal/engine/src/test_support/recording/forward-tests-variants.rs
index e2c166dd5..4513fc291 100644
--- a/crates/runvil-internal/engine/src/test_support/recording/forward-tests-variants.rs
+++ b/crates/runvil-internal/engine/src/test_support/recording/forward-tests-variants.rs
@@ -286,6 +286,7 @@ fn one_of_every_event_variant() -> Vec<(Event, Seam)> {
tool_call_id: "call_1".to_owned(),
alias: "search".to_owned(),
tool: None,
+ vendor: None,
content: "found".to_owned(),
trusted: false,
},
diff --git a/crates/runvil-internal/engine/src/test_support/recording/forward-tests.rs b/crates/runvil-internal/engine/src/test_support/recording/forward-tests.rs
index 5c3b962b5..062d8d29f 100644
--- a/crates/runvil-internal/engine/src/test_support/recording/forward-tests.rs
+++ b/crates/runvil-internal/engine/src/test_support/recording/forward-tests.rs
@@ -243,6 +243,7 @@ fn a_tool_result_forwards_its_coordinates_and_trust_to_the_observer() {
tool_call_id: "call_1".to_owned(),
alias: "search".to_owned(),
tool: None,
+ vendor: None,
content: "found".to_owned(),
trusted,
};
diff --git a/crates/runvil-internal/engine/src/test_support/tools.rs b/crates/runvil-internal/engine/src/test_support/tools.rs
index 3c5c3c04b..1856cce96 100644
--- a/crates/runvil-internal/engine/src/test_support/tools.rs
+++ b/crates/runvil-internal/engine/src/test_support/tools.rs
@@ -24,6 +24,7 @@ pub(crate) struct FnTool {
description: String,
schema: serde_json::Value,
structured: bool,
+ describes_tools: bool,
handler: Arc,
}
@@ -42,6 +43,7 @@ impl FnTool {
description: String::new(),
schema,
structured: false,
+ describes_tools: false,
handler: Arc::new(handler),
}
}
@@ -59,6 +61,13 @@ impl FnTool {
self
}
+ /// Marks the tool as one whose output lists tools, so a script's call
+ /// receives its untrusted output as plain text.
+ pub(crate) fn describes_tools(mut self) -> FnTool {
+ self.describes_tools = true;
+ self
+ }
+
/// The tool's stable identity: the catalog key and what a `ToolCall`
/// effect names.
pub(crate) fn id(&self) -> ToolId {
@@ -68,7 +77,9 @@ impl FnTool {
/// The tool as data: the tool info the Engine binds and advertises,
/// what a scenario installs in the run's catalog.
pub(crate) fn info(&self) -> ToolInfo {
- ToolInfo::new(self.id(), &self.description, self.schema.clone()).structured(self.structured)
+ ToolInfo::new(self.id(), &self.description, self.schema.clone())
+ .structured(self.structured)
+ .describes_tools(self.describes_tools)
}
/// Answers one call with `args` at once.
diff --git a/crates/runvil-internal/lua/src/__impl_coro.lua b/crates/runvil-internal/lua/src/__impl_coro.lua
index 471bd10c5..4373eb813 100644
--- a/crates/runvil-internal/lua/src/__impl_coro.lua
+++ b/crates/runvil-internal/lua/src/__impl_coro.lua
@@ -12,9 +12,9 @@
-- block's raised value for the Engine before the guard re-raises it, and
-- `normalize_failure` turns a Rust callback's raised failure (mlua's
-- opaque userdata) into the error table, passing every other value
--- through unchanged, `enter_local_handler()` and `leave_local_handler()`
--- step the counter the Engine's `jump` reads, so `jump` refuses while a
--- local tool's handler runs, and `cancel_requested()` reports whether the
+-- through unchanged, `enter_adhoc_handler()` and `leave_adhoc_handler()`
+-- step the counter the Engine's `jump` reads, so `jump` refuses while an
+-- adhoc tool's handler runs, and `cancel_requested()` reports whether the
-- run's cancel flag is set: a failure caught under cancellation is the
-- instruction hook's abort, which must unwind to the block guard, so every
-- protected call below raises it again instead of returning it,
@@ -29,7 +29,7 @@
-- `__impl_fanout.lua`), installed by the Engine right after this one over
-- the failure helpers this chunk returns.
local yield, var_snapshot, models, tools, error_value, stash_failure,
- normalize_failure, enter_local_handler, leave_local_handler,
+ normalize_failure, enter_adhoc_handler, leave_adhoc_handler,
cancel_requested, is_model_handle, loop_begin, compact_begin = ...
-- The base library's pcall and xpcall, captured before the replacements
@@ -157,22 +157,22 @@ local function call_section(target, input)
return result
end
--- Runs a local tool's handler inside this block coroutine, so every
+-- Runs an adhoc tool's handler inside this block coroutine, so every
-- suspending call the handler makes is an ordinary yield of the chain.
-- `jump` refuses while the handler runs; the raw pcall catches every
-- failure, so the leave always follows the enter, and it keeps a Rust
-- callback's failure in mlua's own form.
--- The `local_tool_done` yield carries the handler's first return value
+-- The `adhoc_tool_done` yield carries the handler's first return value
-- (only when it returned) for the driver to report; afterward the
-- handler's own failure is raised again unchanged, a rejected return
-- raises the driver's error, and a returned value resumes as its text.
-- A failure under cancellation is raised at once, with no yield.
-local function run_local_tool(handler, args)
- enter_local_handler()
+local function run_adhoc_tool(handler, args)
+ enter_adhoc_handler()
local ok, value = raw_pcall(handler, args)
- leave_local_handler()
+ leave_adhoc_handler()
if not ok and cancel_requested() then error(value, 0) end
- local done = { op = "local_tool_done", ok = ok }
+ local done = { op = "adhoc_tool_done", ok = ok }
if ok then done.value = value end
local answered, result = yield(done)
if not ok then error(value, 0) end
@@ -181,29 +181,29 @@ local function run_local_tool(handler, args)
end
-- One `tool_call` yield and its resume. A bound tool resumes as
--- `(ok, result)`; a local tool resumes as `(true, nil, handler, args)`,
+-- `(ok, result)`; an adhoc tool resumes as `(true, nil, handler, args)`,
-- and the handler runs here.
local function dispatch_tool(request)
local ok, result, handler, args = yield(request)
if not ok then fail(result) end
- if handler ~= nil then return run_local_tool(handler, args) end
+ if handler ~= nil then return run_adhoc_tool(handler, args) end
return result
end
--- Suspending dispatch of a tool. The first argument is a tool id, a local
--- tool's alias, or a tool object; the polymorphism decodes once, in the
--- protocol parse. The driver resumes a bound tool's result by
--- the binding's declared output kind: a plain binding's text as a string,
--- a structured binding's JSON output as a table.
-local function tools_call(alias_or_tool, args)
- return dispatch_tool({ op = "tool_call", alias = alias_or_tool, args = args })
+-- Suspending dispatch of a tool. The first argument is a tool id or a tool
+-- object; the polymorphism decodes once, in the protocol parse. The driver
+-- resumes a bound tool's result by the binding's declared output kind: a
+-- plain binding's text as a string, a structured binding's JSON output as
+-- a table.
+local function tools_call(id_or_tool, args)
+ return dispatch_tool({ op = "tool_call", alias = id_or_tool, args = args })
end
-- The model-issued form of the same dispatch: `call_id` is the id the model
-- attached to its tool call, and `turn` the turn of the round that
-- requested it. The driver always resumes a bound tool with content (a
-- tool's own failure becomes untrusted failure text) and fires ToolResult
--- under the id and that turn, however far a local handler earlier in the
+-- under the id and that turn, however far an adhoc handler earlier in the
-- batch moved the counter. Only the test-only `tools.call_as_model` hook
-- calls it now, since the loop builds its `tool_call` requests in Rust;
-- authors never see it, and a hand-built yield including `call_id` or
@@ -223,7 +223,7 @@ end
-- step returns. A Rust function called from Lua cannot yield, and cannot
-- call a Lua function that may yield, so the step hands back what to do
-- next instead of doing it: yield a request and pass every resume value
--- back; run a local tool's handler between the depth captures, or the
+-- back; run an adhoc tool's handler between the depth captures, or the
-- compactor, under the raw pcall and pass `ok` and the first result back;
-- raise a value at level 0; or return nil. The raw pcall keeps a Rust
-- callback's failure in mlua's own form for the step to judge.
@@ -232,9 +232,9 @@ local function drive(step, action, a, b)
if action == "yield" then
action, a, b = step(yield(a))
elseif action == "handler" then
- enter_local_handler()
+ enter_adhoc_handler()
local ok, value = raw_pcall(a, b)
- leave_local_handler()
+ leave_adhoc_handler()
action, a, b = step(ok, value)
elseif action == "compactor" then
local ok, failure = raw_pcall(a, b)
diff --git a/crates/runvil-internal/lua/src/alias.rs b/crates/runvil-internal/lua/src/alias.rs
index e94465df0..5b385c960 100644
--- a/crates/runvil-internal/lua/src/alias.rs
+++ b/crates/runvil-internal/lua/src/alias.rs
@@ -5,8 +5,8 @@ use crate::error::{Error, Result};
/// A prompt-local alias that passed the supported wire grammar.
///
-/// Local tool aliases and model labels share the one rule. An alias never
-/// contains `/`, so it never reads as a tool id.
+/// An adhoc tool's name and a model label share the one rule. An alias
+/// never contains `/`, so it never reads as a tool id.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct Alias(String);
diff --git a/crates/runvil-internal/lua/src/compactors-tests.rs b/crates/runvil-internal/lua/src/compactors-tests.rs
index 35f8dd921..788916e2f 100644
--- a/crates/runvil-internal/lua/src/compactors-tests.rs
+++ b/crates/runvil-internal/lua/src/compactors-tests.rs
@@ -176,6 +176,7 @@ fn compactors_clear_removes_every_record_and_keeps_the_send_and_the_rendered_too
list.attach_rendered_tools(RenderedTools {
schemas: Vec::new(),
dispatch: BTreeMap::new(),
+ dynamic: Vec::new(),
});
let sent = [Message::user("one")];
let _ = list.commit(RoundId::new(0), &sent);
diff --git a/crates/runvil-internal/lua/src/coro.rs b/crates/runvil-internal/lua/src/coro.rs
index f9bf8a4bd..0952f17a1 100644
--- a/crates/runvil-internal/lua/src/coro.rs
+++ b/crates/runvil-internal/lua/src/coro.rs
@@ -13,12 +13,12 @@
//! frames as verbatim `file:line:` references with no `[string "..."]`
//! wrapper, and the line mapper (`program.rs`) never touches them.
//!
-//! A local tool call is a two-yield handshake inside the calling block
-//! coroutine. The `tools.call` shim yields `tool_call`; for a local alias
+//! An adhoc tool call is a two-yield handshake inside the calling block
+//! coroutine. The `tools.call` shim yields `tool_call`; for an adhoc tool
//! the driver resumes it with the handler instead of a result. The shim
//! calls the handler under a yield-safe `pcall` with `jump` refused, so
//! the handler's own suspending calls are ordinary yields of the same
-//! coroutine, then yields `local_tool_done` with the outcome for the
+//! coroutine, then yields `adhoc_tool_done` with the outcome for the
//! driver to report, and finally returns the text or raises.
#[path = "coro-failure.rs"]
@@ -152,9 +152,9 @@ static FANOUT_PROGRAM: LazyLock> =
/// replacements, which run every caught value through that capture, are
/// installed over the base library's globals here, so an Engine function that
/// fails directly from Rust reaches author code in the one shape. The next
-/// two captures, `enter_local_handler` and `leave_local_handler`, count up
-/// and down on `local_handler_depth`, the counter the VM's `jump` reads, so
-/// `jump` refuses while a local tool's handler runs, whatever reference
+/// two captures, `enter_adhoc_handler` and `leave_adhoc_handler`, count up
+/// and down on `adhoc_handler_depth`, the counter the VM's `jump` reads, so
+/// `jump` refuses while an adhoc tool's handler runs, whatever reference
/// the handler calls it through. Then `cancel_requested` reads the
/// cancel flag of `instruction_budget`, so the chunk's protected calls
/// raise a failure caught under cancellation again instead of returning
@@ -170,7 +170,7 @@ static FANOUT_PROGRAM: LazyLock> =
pub(crate) fn install_shim_prelude(
lua: &Lua,
max_tool_iterations: usize,
- local_handler_depth: &Arc,
+ adhoc_handler_depth: &Arc,
loop_running: &Arc,
instruction_budget: &InstructionBudget,
) -> Result<()> {
@@ -187,8 +187,8 @@ pub(crate) fn install_shim_prelude(
let error_value = install_error_value(lua).map_err(Error::lua)?;
let stash_failure = stash_failure_capture(lua)?;
let normalize_failure = install_normalize_failure(lua).map_err(Error::lua)?;
- let (enter_local_handler, leave_local_handler) =
- local_handler_captures(lua, local_handler_depth)?;
+ let (enter_adhoc_handler, leave_adhoc_handler) =
+ adhoc_handler_captures(lua, adhoc_handler_depth)?;
let budget = instruction_budget.clone();
let cancel_requested = lua
.create_function(move |_, ()| Ok(budget.is_cancelled()))
@@ -215,8 +215,8 @@ pub(crate) fn install_shim_prelude(
error_value,
stash_failure,
normalize_failure,
- enter_local_handler,
- leave_local_handler,
+ enter_adhoc_handler,
+ leave_adhoc_handler,
cancel_requested,
is_model_handle,
loop_begin,
@@ -299,10 +299,10 @@ fn stash_shims(lua: &Lua, shims: &Table) -> Result<()> {
.map_err(Error::lua)
}
-/// Builds the prelude's `enter_local_handler()` and `leave_local_handler()`
+/// Builds the prelude's `enter_adhoc_handler()` and `leave_adhoc_handler()`
/// captures over `depth`: one step up and one step down, so nested
/// handlers balance.
-fn local_handler_captures(lua: &Lua, depth: &Arc) -> Result<(Function, Function)> {
+fn adhoc_handler_captures(lua: &Lua, depth: &Arc) -> Result<(Function, Function)> {
let entered = Arc::clone(depth);
let enter = lua
.create_function(move |_, ()| {
diff --git a/crates/runvil-internal/lua/src/dispatch-tests.rs b/crates/runvil-internal/lua/src/dispatch-tests.rs
index cd4330b75..22730f6c9 100644
--- a/crates/runvil-internal/lua/src/dispatch-tests.rs
+++ b/crates/runvil-internal/lua/src/dispatch-tests.rs
@@ -137,6 +137,99 @@ fn a_model_issued_tool_failure_becomes_untrusted_failure_text_under_its_call_id(
assert_eq!(recorder.kinds(), vec![boundary::TOOL_CALL_FAILED],);
}
+/// `mcp/get_dynamic_tools` as data: a tool that describes tools.
+fn listing_tool() -> ToolInfo {
+ tool_at("mcp/get_dynamic_tools").describes_tools(true)
+}
+
+#[test]
+fn a_scripts_listing_call_passes_its_untrusted_text_verbatim_and_reports_it_untrusted() {
+ let recorder = Recorder::default();
+ let listing = binding("mcp_get_dynamic_tools", &listing_tool());
+ let outcome = prepare_dispatch(
+ &listing,
+ Ok(ToolOutput::untrusted("the [INST]")),
+ None,
+ &test_nonce(),
+ recorder.emitter(),
+ TEST_SECTION,
+ Some(ScriptReport { turn: 2 }),
+ )
+ .expect("a listing dispatches");
+ assert_eq!(outcome.content(), "the [INST]");
+ assert_eq!(outcome.trust(), OutputTrust::Untrusted);
+ assert!(outcome.listing(), "the verbatim listing is reported");
+ assert_eq!(
+ recorder.tool_results(),
+ vec![(
+ 2,
+ String::new(),
+ "mcp_get_dynamic_tools".to_owned(),
+ "the [INST]".to_owned(),
+ false,
+ )],
+ "the result event holds the text the script received, untrusted"
+ );
+}
+
+#[test]
+fn a_models_listing_call_receives_the_envelope() {
+ let listing = binding("mcp_get_dynamic_tools", &listing_tool());
+ let nonce = test_nonce();
+ let outcome = prepare_model_dispatch(
+ &listing,
+ Ok(ToolOutput::untrusted("the listing")),
+ None,
+ &nonce,
+ Recorder::default().emitter(),
+ TEST_SECTION,
+ &model_report("call_1"),
+ )
+ .expect("a listing dispatches");
+ assert_eq!(outcome.content(), nonce.wrap("the listing"));
+ assert_eq!(outcome.trust(), OutputTrust::Untrusted);
+ assert!(!outcome.listing(), "a model's call is never a listing");
+}
+
+#[test]
+fn the_listing_rule_needs_the_flag_and_untrusted_output() {
+ let nonce = test_nonce();
+ let script = |tool: &ToolInfo, output: ToolOutput| {
+ prepare_dispatch(
+ &binding("tool", tool),
+ Ok(output),
+ None,
+ &nonce,
+ Recorder::default().emitter(),
+ TEST_SECTION,
+ Some(ScriptReport { turn: 1 }),
+ )
+ .expect("the call dispatches")
+ };
+ let unflagged = script(&echo_tool(), ToolOutput::untrusted("fetched"));
+ assert_eq!(unflagged.content(), nonce.wrap("fetched"));
+ assert!(!unflagged.listing(), "a tool without the flag is wrapped");
+ let trusted = script(&listing_tool(), ToolOutput::trusted("built in"));
+ assert_eq!(
+ (trusted.content(), trusted.trust(), trusted.listing()),
+ ("built in", OutputTrust::Trusted, false),
+ "a trusted listing passes as any trusted output and is not reported"
+ );
+ let failed = prepare_dispatch(
+ &binding("tool", &listing_tool()),
+ Err(ToolError::message("the servers are down")),
+ None,
+ &nonce,
+ Recorder::default().emitter(),
+ TEST_SECTION,
+ Some(ScriptReport { turn: 1 }),
+ );
+ assert!(
+ matches!(failed, Err(Error::Tool { .. })),
+ "a failed listing is the tool's error: {failed:?}"
+ );
+}
+
#[test]
fn a_model_issued_dispatch_reports_its_result_under_the_call_id() {
let recorder = Recorder::default();
diff --git a/crates/runvil-internal/lua/src/dispatch.rs b/crates/runvil-internal/lua/src/dispatch.rs
index 39ae703cf..1ed503ab7 100644
--- a/crates/runvil-internal/lua/src/dispatch.rs
+++ b/crates/runvil-internal/lua/src/dispatch.rs
@@ -52,34 +52,43 @@ pub struct ModelReport {
}
/// The resolved outcome of one dispatched tool call: the final content -
-/// nonce-wrapped when untrusted - beside its trust marking. A model
-/// tool-loop dispatch reports the pair through the `ToolResult` event
-/// itself; a script-initiated dispatch reads only the content, its report
-/// already fired inside [`prepare_dispatch`].
+/// nonce-wrapped when untrusted, except a script's listing - beside its
+/// trust marking. A model tool-loop dispatch reports the pair through the
+/// `ToolResult` event itself; a script-initiated dispatch reads only the
+/// content, its report already fired inside [`prepare_dispatch`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ToolDispatch {
content: String,
trust: OutputTrust,
+ listing: bool,
}
impl ToolDispatch {
- /// The final content: trusted output verbatim, anything else
- /// nonce-wrapped.
+ /// The final content: trusted output and a script's listing verbatim,
+ /// anything else nonce-wrapped.
#[cfg(test)]
#[must_use]
pub(crate) fn content(&self) -> &str {
&self.content
}
- /// The content's trust marking: [`OutputTrust::Trusted`]
- /// for verbatim output, [`OutputTrust::Untrusted`] for the
- /// nonce-wrapped envelope.
+ /// The content's trust marking: [`OutputTrust::Trusted`] for trusted
+ /// output, [`OutputTrust::Untrusted`] for the nonce-wrapped envelope
+ /// and for a script's listing.
#[cfg(test)]
#[must_use]
pub(crate) fn trust(&self) -> OutputTrust {
self.trust
}
+ /// Whether the content is untrusted text passed verbatim: a script's
+ /// call to a tool that describes tools, answered with untrusted
+ /// output. Trusted output from such a tool is not a listing.
+ #[must_use]
+ pub fn listing(&self) -> bool {
+ self.listing
+ }
+
/// Dissolves the outcome into its content.
#[must_use]
pub fn into_content(self) -> String {
@@ -94,11 +103,14 @@ impl ToolDispatch {
/// executor that counted the attempt at dispatch passes `None`), the
/// succeeded/failed observation,
/// then the trust rule - a trusted output passes verbatim, anything else is
-/// nonce-wrapped before it can reach a model turn or a calling script. A
-/// script-initiated call (`script` is `Some`) also fires
-/// the `ToolResult` event with the final content; a model-loop call
-/// fires no content event here: the loop reports the returned
-/// [`ToolDispatch`] under the model-issued call id.
+/// nonce-wrapped before it can reach a model turn or a calling script,
+/// except that a script-initiated call to a binding that describes tools
+/// receives its untrusted output verbatim, still marked untrusted, as a
+/// listing the script reads. A script-initiated call (`script` is `Some`)
+/// also fires the `ToolResult` event with the final content and the
+/// binding's vendor; a model-loop call fires no content event here: the
+/// loop reports the returned [`ToolDispatch`] under the model-issued call
+/// id.
///
/// `call_result` is the tool's own answer, however the caller obtained it.
/// Nothing here awaits: the Harness performs the call, and the Engine
@@ -130,17 +142,24 @@ pub fn prepare_dispatch(
);
let output = call_result.map_err(Error::tool)?;
// Trust travels with the output: an untrusted result is nonce-wrapped
- // before it can reach the next model turn or the calling script. Every
- // wrap in the run shares the run's nonce, so identical content yields a
- // byte-identical envelope and KV-cache prefixes stay shared across
- // rounds and fanout arms; the `<`-escaping is what actually blocks a
- // forged close tag, so the reuse costs nothing.
- let (content, trust) = match output.trust() {
- OutputTrust::Trusted => (output.text().to_owned(), OutputTrust::Trusted),
+ // before it can reach the next model turn or the calling script, except
+ // a listing a script reads, which passes verbatim. Its `listing` flag
+ // lets the Engine mark the innermost open adhoc call, whose result is
+ // then wrapped before a model reads it; the untrusted marking keeps
+ // this call's result event `trusted` false. Every wrap in the run
+ // shares the run's nonce, so identical content yields a byte-identical
+ // envelope and KV-cache prefixes stay shared across rounds and fanout
+ // arms; the `<`-escaping is what actually blocks a forged close tag, so
+ // the reuse costs nothing.
+ let (content, trust, listing) = match output.trust() {
+ OutputTrust::Trusted => (output.text().to_owned(), OutputTrust::Trusted, false),
+ OutputTrust::Untrusted if script.is_some() && binding.describes_tools() => {
+ (output.text().to_owned(), OutputTrust::Untrusted, true)
+ }
// `OutputTrust` is `#[non_exhaustive]` in the contract crate: an
// unknown future variant takes the safe path and is nonce-wrapped
// as untrusted.
- _ => (nonce.wrap(output.text()), OutputTrust::Untrusted),
+ _ => (nonce.wrap(output.text()), OutputTrust::Untrusted, false),
};
if let Some(report) = script {
emitter.tool_result(
@@ -149,11 +168,16 @@ pub fn prepare_dispatch(
"",
binding.alias(),
Some(binding.id()),
+ binding.vendor(),
&content,
trust,
);
}
- Ok(ToolDispatch { content, trust })
+ Ok(ToolDispatch {
+ content,
+ trust,
+ listing,
+ })
}
/// Applies the model-issued dispatch rules to one bound tool call's answer:
@@ -185,6 +209,7 @@ pub fn prepare_model_dispatch(
Err(Error::Tool { message, .. }) => ToolDispatch {
content: nonce.wrap(&message),
trust: OutputTrust::Untrusted,
+ listing: false,
},
Err(error) => return Err(error),
};
@@ -194,6 +219,7 @@ pub fn prepare_model_dispatch(
&report.call_id,
binding.alias(),
Some(binding.id()),
+ binding.vendor(),
&outcome.content,
outcome.trust,
);
diff --git a/crates/runvil-internal/lua/src/globals.rs b/crates/runvil-internal/lua/src/globals.rs
index bb2e3a2d0..b6053fdd7 100644
--- a/crates/runvil-internal/lua/src/globals.rs
+++ b/crates/runvil-internal/lua/src/globals.rs
@@ -204,7 +204,7 @@ impl fmt::Display for Reserved {
/// A global section setup installs must be listed here: the Engine's
/// section setup tests compare this list against a set-up VM's globals in
/// both directions.
-pub const RESERVED_NAMES: [(&str, Reserved); 63] = [
+pub const RESERVED_NAMES: [(&str, Reserved); 62] = [
("args", Reserved::EngineGlobal),
("argv", Reserved::EngineGlobal),
("call", Reserved::EngineGlobal),
@@ -215,7 +215,6 @@ pub const RESERVED_NAMES: [(&str, Reserved); 63] = [
("log", Reserved::EngineGlobal),
("messages", Reserved::EngineGlobal),
("models", Reserved::EngineGlobal),
- ("packs", Reserved::EngineGlobal),
("prompt", Reserved::EngineGlobal),
("prose", Reserved::EngineGlobal),
("require", Reserved::EngineGlobal),
diff --git a/crates/runvil-internal/lua/src/handles.rs b/crates/runvil-internal/lua/src/handles.rs
index 2038e5f4e..8abdfe9af 100644
--- a/crates/runvil-internal/lua/src/handles.rs
+++ b/crates/runvil-internal/lua/src/handles.rs
@@ -25,8 +25,8 @@ pub enum ToolOutputKind {
}
/// One catalog tool bound under the name a model sees, holding the tool's
-/// data - its schema, description, and output kind - and never its
-/// implementation.
+/// data - its schema, description, output kind, whether it lists tools,
+/// and its Pack's vendor - and never its implementation.
///
/// Run-time execution (schema preparation, script dispatch) reads the
/// binding alone; a call is issued as an effect naming the identity, and
@@ -46,12 +46,18 @@ pub struct ToolBinding {
/// How a script-initiated `tools.call` resumes this binding's output;
/// the model tool loop ignores it.
output_kind: ToolOutputKind,
+ /// Whether the tool's output lists tools, which a script's call
+ /// receives as plain text.
+ describes_tools: bool,
+ /// The vendor of the tool's Pack, as the caller reported it.
+ vendor: Option,
}
impl ToolBinding {
/// Binds `alias` to the tool `info` describes: the description is the
- /// tool's own, and the output kind follows the tool info's
- /// structured-output flag.
+ /// tool's own, the output kind follows the tool info's
+ /// structured-output flag, and the listing flag is the tool info's.
+ /// The binding names no vendor.
#[must_use]
pub fn from_info(alias: &str, info: &ToolInfo) -> Self {
Self {
@@ -64,9 +70,18 @@ impl ToolBinding {
} else {
ToolOutputKind::Plain
},
+ describes_tools: info.describes_tools,
+ vendor: None,
}
}
+ /// Sets the vendor of the tool's Pack, as the caller reported it.
+ #[must_use]
+ pub fn with_vendor(mut self, vendor: Option) -> Self {
+ self.vendor = vendor;
+ self
+ }
+
/// Returns the model-facing name.
#[must_use]
pub fn alias(&self) -> &str {
@@ -97,6 +112,19 @@ impl ToolBinding {
pub fn output_kind(&self) -> ToolOutputKind {
self.output_kind
}
+
+ /// Returns whether the tool's output lists tools.
+ #[must_use]
+ pub fn describes_tools(&self) -> bool {
+ self.describes_tools
+ }
+
+ /// Returns the vendor of the tool's Pack, as the caller reported it
+ /// for the run, or `None` when it reported none.
+ #[must_use]
+ pub fn vendor(&self) -> Option<&str> {
+ self.vendor.as_deref()
+ }
}
/// Outcome of a Lua block that may invoke `jump`.
@@ -227,8 +255,8 @@ impl ToolSet {
}
/// Returns the offered binding whose wire name or canonical id is
- /// `name`, which matches at most one way because wire names and local
- /// aliases never contain `/` and ids always do.
+ /// `name`, which matches at most one way because wire names never
+ /// contain `/` and ids always do.
#[must_use]
pub fn offered_binding(&self, name: &str) -> Option<&ToolBinding> {
if name.contains('/') {
diff --git a/crates/runvil-internal/lua/src/json.rs b/crates/runvil-internal/lua/src/json.rs
index 571a0e777..0a367aa03 100644
--- a/crates/runvil-internal/lua/src/json.rs
+++ b/crates/runvil-internal/lua/src/json.rs
@@ -14,6 +14,8 @@ mod decode;
mod encode;
mod keys;
+pub(crate) use encode::to_json;
+
use mlua::{Lua, LuaSerdeExt, Table, Value};
use crate::error::{Error, Result};
diff --git a/crates/runvil-internal/lua/src/json/encode.rs b/crates/runvil-internal/lua/src/json/encode.rs
index efb4d4d15..5179a3b86 100644
--- a/crates/runvil-internal/lua/src/json/encode.rs
+++ b/crates/runvil-internal/lua/src/json/encode.rs
@@ -32,12 +32,24 @@ const DEPTH_LIMIT: usize = 127;
pub(super) fn encode(lua: &Lua, (value, options): (Value, Value)) -> mlua::Result {
const FUNCTION: &str = "json.encode";
let debug = debug_option(&options, FUNCTION)?;
- let json = Encoder::new(lua, FUNCTION, debug).value(&value, 1)?;
+ let json = to_json(lua, FUNCTION, debug, &value)?;
let text =
serde_json::to_string(&json).map_err(|error| refusal(format!("{FUNCTION}: {error}")))?;
lua.create_string(text)
}
+/// The JSON value `value` converts to under the `json.encode` rules, in
+/// debug mode when `debug` is set. Every refusal reads `: ` and
+/// then the reason, which names the failing path from `value`.
+pub(crate) fn to_json(
+ lua: &Lua,
+ prefix: &'static str,
+ debug: bool,
+ value: &Value,
+) -> mlua::Result {
+ Encoder::new(lua, prefix, debug).value(value, 1)
+}
+
/// `json.encode_lines(list [, options])`: each item of `list` encoded by
/// the `json.encode` rules and followed by a newline.
pub(super) fn encode_lines(lua: &Lua, (list, options): (Value, Value)) -> mlua::Result {
diff --git a/crates/runvil-internal/lua/src/lib.rs b/crates/runvil-internal/lua/src/lib.rs
index d7df4460d..86a7afcf1 100644
--- a/crates/runvil-internal/lua/src/lib.rs
+++ b/crates/runvil-internal/lua/src/lib.rs
@@ -37,15 +37,13 @@
//! raw-set into `_G`. The `input` table that `user-input` defines is one:
//! `input.ask()` is an ordinary tool call to that Pack's ask tool.
//!
-//! The `tools` table names every catalog tool the run can offer by its
-//! canonical id: `tools.required()` and `tools.extras()` list the tool
-//! objects of the declared Packs and of every other Pack, and
-//! `tools.offer` scopes a tool into a section by id or tool object. The
-//! `packs` table holds one object per Pack the run knows, whose
-//! `tools` lists that Pack's tool objects, and `packs.offer` scopes
-//! every tool of a Pack into a section. Offers work only before the
-//! section's first loop round, which renders the section's tool list;
-//! after that, every offer function raises.
+//! The `tools` table names every tool by its id: `tools.get` reads a tool
+//! object, `tools.packs` holds one object per Pack the run knows, the
+//! adhoc Pack included, whose `tools` lists that Pack's tool objects, and
+//! `tools.adhoc` defines a Lua function as a tool of the adhoc Pack.
+//! `tools.offer` and `tools.offer_dynamic` remember tools and Packs, by
+//! id or object, for the section's rendered and dynamic lists, which the
+//! section's first loop round builds; after that, every offer raises.
//!
//! `messages` is the section's one conversation: a list the VM creates
//! empty at each section entry and serves as a global that no assignment
@@ -137,13 +135,15 @@ pub use crate::program::LuaProgram;
pub use crate::projection::project_messages;
pub use crate::prose::ProseState;
pub use crate::protocol::{
- Answer, Blocked, ChatOutcome, ChatResult, ContentPart, LocalToolOutcome, MessageContent,
+ AdhocToolOutcome, Answer, Blocked, ChatOutcome, ChatResult, ContentPart, MessageContent,
MessageRecord, NonEmpty, RecordRole, Request, SpawnVia, TaskDelivery, TaskPhase, TaskStatus,
ToolCallOutcome, ToolCallRecord, VfsOp, VfsOutcome, YieldParse,
};
-pub use crate::scope::{RenderedTools, ToolCallCounts, ToolRuntime};
+pub use crate::scope::{
+ Advertised, Offer, OfferMode, OfferTarget, RenderedTools, ToolCallCounts, ToolRuntime,
+};
pub use crate::sys::enrich_sys_model;
pub use crate::vm::{
- CoroStep, InjectFailure, Injected, SectionVm, Uninjected, current_tool_bindings,
- resolve_model_binding,
+ AdhocTools, CoroStep, InjectFailure, Injected, SectionVm, Uninjected, current_dynamic_tools,
+ current_tool_bindings, resolve_model_binding,
};
diff --git a/crates/runvil-internal/lua/src/messages-tests.rs b/crates/runvil-internal/lua/src/messages-tests.rs
index fe357065d..13228350a 100644
--- a/crates/runvil-internal/lua/src/messages-tests.rs
+++ b/crates/runvil-internal/lua/src/messages-tests.rs
@@ -4,13 +4,14 @@
use std::collections::BTreeMap;
use mlua::{Lua, LuaSerdeExt, Value};
+use runvil_types::tools::ToolId;
use serde_json::json;
use super::MessageList;
use crate::protocol::{Request, YieldParse};
use crate::test_vm::TestVm;
use crate::tests::{system, user};
-use crate::{Error, RenderedTools};
+use crate::{Advertised, Error, RenderedTools};
#[path = "messages-tests-list.rs"]
mod list;
@@ -45,14 +46,23 @@ fn messages_is_the_vms_one_empty_list_and_lua_reaches_no_other() {
assert_eq!(vm.messages().to_records(), vec![user("u")]);
}
-/// A rendered tool list advertising each of `names` as a local tool.
+/// The advertised entry of the adhoc tool named `name`.
+fn adhoc(name: &str) -> Advertised {
+ Advertised {
+ id: ToolId::parse(&format!("adhoc/{name}")).expect("a fixture adhoc id is a tool id"),
+ vendor: None,
+ }
+}
+
+/// A rendered tool list advertising each of `names` as an adhoc tool.
fn rendered(names: &[&str]) -> RenderedTools {
RenderedTools {
schemas: Vec::new(),
dispatch: names
.iter()
- .map(|name| ((*name).to_owned(), None))
+ .map(|name| ((*name).to_owned(), adhoc(name)))
.collect(),
+ dynamic: Vec::new(),
}
}
@@ -69,9 +79,15 @@ fn a_list_is_rendered_only_once_a_tool_list_is_attached_and_keeps_the_first() {
.expect("the list holds a rendered tool list");
assert_eq!(
kept.dispatch,
- BTreeMap::from([("first".to_owned(), None)]),
+ BTreeMap::from([("first".to_owned(), adhoc("first"))]),
"the first attached list stays"
);
+ assert_eq!(
+ list.rendered_target("first"),
+ Some(adhoc("first")),
+ "the attached list's entry reads by wire name"
+ );
+ assert_eq!(list.rendered_target("second"), None);
}
#[test]
diff --git a/crates/runvil-internal/lua/src/messages.rs b/crates/runvil-internal/lua/src/messages.rs
index d80e8eb89..6a41c975b 100644
--- a/crates/runvil-internal/lua/src/messages.rs
+++ b/crates/runvil-internal/lua/src/messages.rs
@@ -41,7 +41,7 @@ use serde_json::{Map, Value as Json};
use crate::error::{Error, Result};
use crate::protocol::{MessageRecord, RecordRole, parse_record};
-use crate::scope::RenderedTools;
+use crate::scope::{Advertised, RenderedTools};
#[path = "messages-snapshot.rs"]
mod snapshot;
@@ -217,6 +217,14 @@ impl MessageList {
self.state().rendered.clone()
}
+ /// The attached rendered list's entry for `wire_name`, if a list is
+ /// attached and advertises that name.
+ #[must_use]
+ pub(crate) fn rendered_target(&self, wire_name: &str) -> Option {
+ let state = self.state();
+ state.rendered.as_ref()?.dispatch.get(wire_name).cloned()
+ }
+
/// Attaches `tools` as the section's rendered tool list. A list that
/// already holds one keeps it.
///
diff --git a/crates/runvil-internal/lua/src/models_loop.rs b/crates/runvil-internal/lua/src/models_loop.rs
index 2fe543804..545d210b0 100644
--- a/crates/runvil-internal/lua/src/models_loop.rs
+++ b/crates/runvil-internal/lua/src/models_loop.rs
@@ -11,7 +11,7 @@
//! each step returns to the trampoline with one action, named by its tag:
//! `"yield"` a request and
//! pass every resume value back; call a `"handler"` between
-//! `enter_local_handler()` and `leave_local_handler()`, or the
+//! `enter_adhoc_handler()` and `leave_adhoc_handler()`, or the
//! `"compactor"`, under the raw `pcall` and pass `ok` and the first
//! result back; `"raise"` a value with `error(value, 0)`; or `"return"`
//! nil. This adapter reads the values the trampoline passes into the
@@ -304,7 +304,7 @@ fn read_input(
Phase::Calling => {
let handler = next();
if ok && !handler.is_nil() {
- return Ok(Input::Local {
+ return Ok(Input::Adhoc {
handler,
args: next(),
});
@@ -376,7 +376,7 @@ fn act(lua: &Lua, then: Then) -> mlua::Result {
Then::Report(returned) => {
let ok = Value::Boolean(returned.is_some());
let fields = [("ok", ok), ("value", returned.unwrap_or(Value::Nil))];
- ("yield", vec![request(lua, "local_tool_done", fields)?])
+ ("yield", vec![request(lua, "adhoc_tool_done", fields)?])
}
Then::Return => ("return", Vec::new()),
Then::Raise(value) => ("raise", vec![value]),
diff --git a/crates/runvil-internal/lua/src/models_loop/machine-tests.rs b/crates/runvil-internal/lua/src/models_loop/machine-tests.rs
index f159b7fac..f48c4fc4d 100644
--- a/crates/runvil-internal/lua/src/models_loop/machine-tests.rs
+++ b/crates/runvil-internal/lua/src/models_loop/machine-tests.rs
@@ -311,7 +311,7 @@ fn a_failed_answer_raises_its_value_unchanged() {
);
}
-/// A machine waiting on a local call's handler, over `list`.
+/// A machine waiting on an adhoc call's handler, over `list`.
fn handling(list: &MessageList) -> Machine {
let mut machine = chatting(2, list);
machine.step(batch(&["c1"]));
@@ -319,16 +319,16 @@ fn handling(list: &MessageList) -> Machine {
show(&machine.step(batched(&[]))),
r#"tool_call c1 echo {"id":"c1"}@7"#
);
- let local = Input::Local {
+ let adhoc = Input::Adhoc {
handler: "handler",
args: "args",
};
- assert_eq!(show(&machine.step(local)), "handle handler args");
+ assert_eq!(show(&machine.step(adhoc)), "handle handler args");
machine
}
#[test]
-fn a_local_call_reports_its_outcome_then_raises_the_handlers_value_first() {
+fn an_adhoc_call_reports_its_outcome_then_raises_the_handlers_value_first() {
let list = MessageList::default();
let mut machine = handling(&list);
assert_eq!(
diff --git a/crates/runvil-internal/lua/src/models_loop/machine.rs b/crates/runvil-internal/lua/src/models_loop/machine.rs
index b748cc15b..4d65ba638 100644
--- a/crates/runvil-internal/lua/src/models_loop/machine.rs
+++ b/crates/runvil-internal/lua/src/models_loop/machine.rs
@@ -1,6 +1,6 @@
//! The rules of `models.loop` over typed inputs, with no Lua VM: the
-//! round cap, the order a round's answer is judged in, the batch rule, a
-//! local tool's report and re-raise, and compaction after an overflow.
+//! round cap, the order a round's answer is judged in, the batch rule, an
+//! adhoc tool's report and re-raise, and compaction after an overflow.
//! The machine pushes every record onto the list itself, and every Lua
//! value it only passes along is an opaque `V`, so the unit tests run over
//! a plain `MessageList` with any `V`.
@@ -93,7 +93,7 @@ pub(super) enum Phase {
Calling,
/// The handler's raw `pcall`: `(ok, value)`.
Handling,
- /// The `local_tool_done` answer: `(ok, text)`, with the handler's own
+ /// The `adhoc_tool_done` answer: `(ok, text)`, with the handler's own
/// raised value when it raised.
Reporting(Option),
/// The loop returned or raised.
@@ -111,15 +111,15 @@ pub(super) enum Input {
Batched(std::result::Result, V>),
/// A bound tool's text, or the value to raise.
Dispatched(std::result::Result),
- /// A local tool's handler and its arguments table.
- Local { handler: V, args: V },
+ /// An adhoc tool's handler and its arguments table.
+ Adhoc { handler: V, args: V },
/// The compactor's or the handler's raw `pcall`: its first returned
/// or raised value, and whether the run's cancel flag was set.
Called {
outcome: std::result::Result,
cancelled: bool,
},
- /// The `local_tool_done` answer: the call's text, or the value to
+ /// The `adhoc_tool_done` answer: the call's text, or the value to
/// raise.
Reported(std::result::Result),
}
@@ -137,7 +137,7 @@ pub(super) enum Then {
},
/// Yield `{ op = "tool_call", alias = call.name, args = call.arguments,
/// call_id = call.id, turn = turn }`.
- ToolCall { call: ToolCallEvent, turn: u32 },
+ ToolCall { call: Box, turn: u32 },
/// Call the compactor with the reason's tag.
Compact {
compactor: V,
@@ -145,8 +145,8 @@ pub(super) enum Then {
},
/// Call the handler with its arguments table.
Handle { handler: V, args: V },
- /// Yield `{ op = "local_tool_done", ok = true, value = value }` when
- /// the handler returned, or `{ op = "local_tool_done", ok = false }`
+ /// Yield `{ op = "adhoc_tool_done", ok = true, value = value }` when
+ /// the handler returned, or `{ op = "adhoc_tool_done", ok = false }`
/// when it raised.
Report(Option),
/// Return nil.
@@ -226,7 +226,7 @@ impl Machine {
self.results.push(text);
self.next_call()
}
- (Phase::Calling, Input::Local { handler, args }) => {
+ (Phase::Calling, Input::Adhoc { handler, args }) => {
self.phase = Phase::Handling;
Then::Handle { handler, args }
}
@@ -338,7 +338,7 @@ impl Machine {
Some(call) if short => {
self.phase = Phase::Calling;
Then::ToolCall {
- call: call.clone(),
+ call: Box::new(call.clone()),
turn: self.turn,
}
}
diff --git a/crates/runvil-internal/lua/src/models_loop/tests.rs b/crates/runvil-internal/lua/src/models_loop/tests.rs
index 8c71b320e..d55ab80ff 100644
--- a/crates/runvil-internal/lua/src/models_loop/tests.rs
+++ b/crates/runvil-internal/lua/src/models_loop/tests.rs
@@ -19,7 +19,7 @@ use crate::error_value::{ErrorField, ErrorKind, Raised, error_table, raised_from
use crate::hardening::InstructionBudget;
use crate::messages::MessageList;
use crate::models::LuaModelHandle;
-use crate::protocol::{Answer, ChatOutcome, ChatResult, LocalToolOutcome, Request, YieldParse};
+use crate::protocol::{AdhocToolOutcome, Answer, ChatOutcome, ChatResult, Request, YieldParse};
/// A requested call named `echo`, its arguments naming its id.
pub(super) fn echo_call(id: &str) -> ToolCallEvent {
@@ -339,7 +339,7 @@ fn parsed(lua: &Lua, then: Then) -> Request {
fn act_yields_each_request_as_the_protocol_parses_it() {
let lua = Lua::new();
let tool_call = Then::ToolCall {
- call: echo_call("c1"),
+ call: Box::new(echo_call("c1")),
turn: 7,
};
let Request::ToolCall {
@@ -358,14 +358,14 @@ fn act_yields_each_request_as_the_protocol_parses_it() {
assert_eq!(args, json!({ "id": "c1" }));
let returned = Value::String(lua.create_string("text").unwrap());
let outcome = |then| match parsed(&lua, then) {
- Request::LocalToolDone { outcome } => outcome,
- other => panic!("a local_tool_done request, got {other:?}"),
+ Request::AdhocToolDone { outcome } => outcome,
+ other => panic!("an adhoc_tool_done request, got {other:?}"),
};
let done = outcome(Then::Report(Some(returned)));
- assert!(matches!(done, LocalToolOutcome::Returned(text) if text == "text"));
+ assert!(matches!(done, AdhocToolOutcome::Returned(text) if text == "text"));
assert!(matches!(
outcome(Then::Report(None)),
- LocalToolOutcome::Raised
+ AdhocToolOutcome::Raised
));
let list = Value::UserData(lua.create_userdata(MessageList::default()).unwrap());
let receiver = handle(&lua);
diff --git a/crates/runvil-internal/lua/src/packs-tests.rs b/crates/runvil-internal/lua/src/packs-tests.rs
index 201360b73..7c802cbf9 100644
--- a/crates/runvil-internal/lua/src/packs-tests.rs
+++ b/crates/runvil-internal/lua/src/packs-tests.rs
@@ -1,68 +1,15 @@
-//! Tests for the `packs` table: the `required` and `extras` lists,
-//! `packs.get`, the shared Pack objects and their `tools`, a tool
-//! object's `pack` getter, and the roster's usable and unavailable
+//! Tests for the Pack objects and `tools.packs`: the walk in name order,
+//! `get` and `extras`, the frozen proxy, `required`, shared objects, names
+//! that collide with members, and the roster's usable and unavailable
//! Packs.
use std::collections::BTreeMap;
use runvil_types::packs::PackId;
+use crate::ToolBinding;
use crate::handles::ToolSet;
-use crate::test_vm::{lua_over, scoped, tool_at};
-use crate::{SectionVm, ToolBinding};
-
-/// A set declaring `web` and then `mail`, which offers no tool, beside the
-/// undeclared Packs `alpha` and `gh`, every tool in id order under its
-/// wire name.
-fn pack_set() -> ToolSet {
- let bind = |id: &str| ToolBinding::from_info(&id.replace(['/', '.'], "_"), &tool_at(id));
- ToolSet::new(
- vec![
- PackId::parse("web").expect("`web` is a valid Pack id"),
- PackId::parse("mail").expect("`mail` is a valid Pack id"),
- ],
- BTreeMap::new(),
- vec![
- bind("alpha/zed"),
- bind("gh/issues.list"),
- bind("gh/search"),
- bind("web/fetch"),
- bind("web/search"),
- ],
- )
-}
-
-/// [`pack_set`] with a roster: `web` and `gh`, which also offer tools,
-/// and `subagents`, which offers none, can serve the run, and `mcp`
-/// can't.
-fn roster_set() -> ToolSet {
- let pack = |name: &str| PackId::parse(name).expect("each roster name is a valid Pack id");
- let base = pack_set();
- ToolSet::new(
- base.declared().to_vec(),
- [
- (pack("gh"), None),
- (pack("mcp"), Some("the mcp server is down".to_owned())),
- (pack("subagents"), None),
- (pack("web"), None),
- ]
- .into_iter()
- .collect(),
- base.offered().to_vec(),
- )
-}
-
-/// The Packs `packs.offer` recorded on `vm`, by name.
-#[track_caller]
-fn offered_packs(vm: &SectionVm) -> Vec {
- vm.tool_runtime()
- .lock()
- .expect("the runtime mutex is not poisoned")
- .packs
- .iter()
- .map(ToString::to_string)
- .collect()
-}
+use crate::test_vm::{lua_over, offer_set, offers, raised, scoped, tool_at};
/// A Lua helper joining the `name` of each Pack object in a list.
const NAMES: &str = "local function names(list)\n\
@@ -71,84 +18,187 @@ const NAMES: &str = "local function names(list)\n\
return table.concat(out, ',')\n\
end\n";
+/// A set declaring `mail`, which offers no tool, beside the undeclared
+/// Packs `get`, `extras`, and `tools`, whose names a member of
+/// `tools.packs` or a Pack object also has.
+fn colliding_set() -> ToolSet {
+ let bind = |id: &str| ToolBinding::from_info(&id.replace(['/', '.'], "_"), &tool_at(id));
+ ToolSet::new(
+ vec![PackId::parse("mail").expect("`mail` is a valid Pack id")],
+ BTreeMap::new(),
+ vec![bind("extras/list"), bind("get/one"), bind("tools/tools")],
+ )
+}
+
#[test]
-fn required_lists_every_declared_pack_in_name_order_and_extras_the_rest() {
- let vm = lua_over(pack_set());
- let result: (String, String, i64, String, bool, bool, String) = vm.eval(&format!(
+fn tools_packs_walks_every_pack_object_in_name_order_the_adhoc_pack_included() {
+ let vm = lua_over(offer_set());
+ let walked: (String, String, String, i64, bool) = vm.eval(&format!(
"{NAMES}\
- local ok, err = pcall(packs.get, 42)\n\
- assert(not ok, 'a non-string is refused')\n\
- return names(packs.required()), names(packs.extras()), \
- #packs.get('mail').tools, packs.get('gh').name, \
- packs.get('missing') == nil, packs.get('web/fetch') == nil, \
- tostring(err)"
+ local indexed = {{}}\n\
+ for i = 1, #tools.packs do indexed[i] = tools.packs[i] end\n\
+ local paired, keys = {{}}, {{}}\n\
+ for key, pack in pairs(tools.packs) do\n\
+ keys[#keys + 1] = type(key)\n\
+ paired[#paired + 1] = pack\n\
+ end\n\
+ return names(tools.packs), names(indexed), names(paired), #tools.packs, \
+ table.concat(keys, ',') == 'number,number,number,number,number'"
));
+ let order = "adhoc,gh,subagents,user-input,web";
assert_eq!(
- result.0, "mail,web",
- "every declared Pack is required, in name order"
+ walked,
+ (
+ order.to_owned(),
+ order.to_owned(),
+ order.to_owned(),
+ 5,
+ true
+ ),
+ "ipairs, integer keys, and pairs walk the Pack objects in name order, and \
+ pairs yields only Packs"
+ );
+}
+
+#[test]
+fn get_returns_a_shared_object_or_nil_and_refuses_anything_but_one_pack_id() {
+ let vm = lua_over(offer_set());
+ let read: (bool, bool, bool, bool, bool) = vm.eval(
+ "local web = tools.packs.get('web')\n\
+ return web == tools.packs.get('web'), web == tools.packs[5], \
+ tools.get('web/search').pack == web, tools.packs.get('missing') == nil, \
+ tools.packs.get('web/search') == nil",
);
assert_eq!(
- result.1, "alpha,gh",
- "every other Pack with offered tools is an extra, in name order"
+ read,
+ (true, true, true, true, true),
+ "one object per Pack across get, integer keys, and tool.pack; nil for an \
+ unknown name and a tool id"
);
- assert_eq!(result.2, 0, "a declared Pack with no tool has an object");
- assert_eq!(result.3, "gh", "packs.get reads an extra by name");
- assert!(
- result.4 && result.5,
- "an unknown name and a tool id read nil: {result:?}"
+ for (call, kind) in [
+ ("tools.packs.get(42)", "integer"),
+ ("tools.packs.get({ 'web', 'subagents' })", "table"),
+ ("tools.packs.get()", "nil"),
+ ] {
+ let error = raised(&vm, call);
+ assert!(
+ error.contains(&format!("tools.packs.get takes one Pack id, got {kind}")),
+ "{call}: {error}"
+ );
+ }
+}
+
+#[test]
+fn tools_packs_is_a_frozen_proxy_whose_other_keys_read_nil() {
+ let vm = lua_over(offer_set());
+ let reads: (bool, bool, bool, String) = vm.eval(
+ "return tools.packs['web'] == nil, tools.packs['name'] == nil, tools.packs[99] == nil, \
+ tostring(getmetatable(tools.packs))",
);
+ assert_eq!(
+ reads,
+ (true, true, true, "tools.packs is read-only".to_owned())
+ );
+ for write in [
+ "tools.packs.get = nil",
+ "tools.packs[1] = 'web'",
+ "tools.packs['web'] = 1",
+ ] {
+ let error = raised(&vm, write);
+ assert!(
+ error.contains("tools.packs is read-only"),
+ "{write}: {error}"
+ );
+ }
+ let error = raised(&vm, "setmetatable(tools.packs, nil)");
assert!(
- result.6.contains("packs.get takes a Pack id, got integer"),
- "the refusal names the type: {}",
- result.6
+ error.contains("cannot change a protected metatable"),
+ "the metatable is protected: {error}"
);
+ let still: String = vm.eval("return tools.packs.get('web').name");
+ assert_eq!(still, "web");
}
#[test]
-fn packs_get_returns_the_one_object_required_and_extras_hand_out() {
- let vm = lua_over(pack_set());
- let result: (bool, bool, bool, bool, bool) = vm.eval(
- "local required = packs.required()\n\
- return packs.get('web') == packs.get('web'), \
- required[2] == packs.get('web'), \
- packs.extras()[2] == packs.get('gh'), \
- packs.required() ~= required, \
- packs.extras() ~= packs.extras()",
- );
+fn extras_are_the_usable_undeclared_packs_in_a_fresh_array() {
+ let vm = lua_over(offer_set());
+ let result: (String, bool, bool) = vm.eval(&format!(
+ "{NAMES}\
+ local extras = tools.packs.extras()\n\
+ return names(extras), extras ~= tools.packs.extras(), \
+ extras[1] == tools.packs.get('gh')"
+ ));
assert_eq!(
result,
- (true, true, true, true, true),
- "one object per Pack, handed out in a fresh array per list call"
+ ("gh,subagents".to_owned(), true, true),
+ "never a declared Pack, the adhoc Pack, or a Pack that cannot serve"
);
}
#[test]
-fn a_packs_tools_are_the_shared_tool_objects_in_a_fresh_array_that_offer_takes() {
- let vm = lua_over(pack_set());
- let result: (i64, bool, bool, bool) = vm.eval(
- "local web = packs.get('web')\n\
- local tools_list = web.tools\n\
- tools.offer(web.tools)\n\
- return #tools_list, tools_list[1] == tools.get('web/fetch'), \
- tools_list[2] == tools.get('web/search'), web.tools ~= tools_list",
+fn required_is_true_only_for_a_declared_pack() {
+ let vm = lua_over(colliding_set());
+ let required: (bool, bool, bool, bool, bool) = vm.eval(
+ "return tools.packs.get('mail').required, tools.packs.get('tools').required, \
+ tools.packs.get('adhoc').required, #tools.packs.get('tools').tools > 0, \
+ #tools.packs.get('mail').tools > 0",
);
assert_eq!(
- result,
- (2, true, true, true),
- "a Pack's tools are its shared tool objects, in id order, in a new array per read"
+ required,
+ (true, false, false, true, false),
+ "a declared Pack is required even with no tools, and #pack.tools tells \
+ whether it has tools"
+ );
+}
+
+#[test]
+fn packs_whose_names_collide_with_members_are_reached_through_get_and_offered_by_id() {
+ let vm = lua_over(colliding_set());
+ let reads: (String, String, String, String, bool, bool) = vm.eval(
+ "return tools.packs.get('get').name, tools.packs.get('extras').name, \
+ tools.packs.get('tools').name, tools.packs.get('tools').tools[1].id, \
+ type(tools.packs.get) == 'function', type(tools.packs.extras) == 'function'",
);
assert_eq!(
- scoped(&vm),
- ["web_fetch", "web_search"],
- "tools.offer takes a Pack's tools array"
+ reads,
+ (
+ "get".to_owned(),
+ "extras".to_owned(),
+ "tools".to_owned(),
+ "tools/tools".to_owned(),
+ true,
+ true
+ )
+ );
+ vm.exec("tools.offer({ 'get', 'extras', 'tools' })");
+ assert_eq!(offers(&vm), ["static:get", "static:extras", "static:tools"]);
+ assert_eq!(scoped(&vm), ["get_one", "extras_list", "tools_tools"]);
+}
+
+#[test]
+fn pack_and_tool_objects_hold_no_field_beyond_their_own() {
+ let vm = lua_over(colliding_set());
+ let extra: Option = vm.eval(
+ "local probes = {\n\
+ { tools.packs.get('tools'), { 'get', 'extras', 'id', 'vendor', 'pack' } },\n\
+ { tools.get('tools/tools'), { 'tools', 'name', 'required', 'vendor', 'alias' } },\n\
+ }\n\
+ for _, probe in ipairs(probes) do\n\
+ for _, field in ipairs(probe[2]) do\n\
+ local ok, value = pcall(function() return probe[1][field] end)\n\
+ if ok and value ~= nil then return field end\n\
+ end\n\
+ end\n\
+ return nil",
);
+ assert_eq!(extra, None);
}
#[test]
fn assigning_a_field_on_a_pack_object_is_refused() {
- let vm = lua_over(pack_set());
+ let vm = lua_over(offer_set());
let (name, extra, read): (String, String, String) = vm.eval(
- "local web = packs.get('web')\n\
+ "local web = tools.packs.get('web')\n\
local _, name = pcall(function() web.name = 'x' end)\n\
local _, extra = pcall(function() web.extra = 1 end)\n\
return tostring(name), tostring(extra), web.name",
@@ -165,136 +215,55 @@ fn assigning_a_field_on_a_pack_object_is_refused() {
}
#[test]
-fn every_tool_objects_pack_is_its_packs_object() {
- let vm = lua_over(pack_set());
- let mismatched: String = vm.eval(
- "local bad = {}\n\
- for _, list in ipairs({ tools.required(), tools.extras() }) do\n\
- for _, tool in ipairs(list) do\n\
- local name = tool.id:match('^[^/]+')\n\
- if tool.pack ~= packs.get(name) or tool.pack.name ~= name then\n\
- bad[#bad + 1] = tool.id\n\
- end\n\
- end\n\
- end\n\
- assert(#tools.required() + #tools.extras() == 5, 'every tool is walked')\n\
- return table.concat(bad, ',')",
+fn a_packs_tools_are_the_shared_tool_objects_in_a_fresh_array_that_offer_takes() {
+ let vm = lua_over(offer_set());
+ let result: (i64, bool, bool, bool) = vm.eval(
+ "local web = tools.packs.get('web')\n\
+ local tools_list = web.tools\n\
+ tools.offer(web.tools)\n\
+ return #tools_list, tools_list[1] == tools.get('web/fetch'), \
+ tools_list[2] == tools.get('web/search'), web.tools ~= tools_list",
);
assert_eq!(
- mismatched, "",
- "each tool object's pack is == to its Pack's object"
- );
-}
-
-#[test]
-fn packs_is_the_engine_global_and_the_old_plugins_global_is_nil() {
- let vm = lua_over(pack_set());
- let (installed, gone, error): (bool, bool, String) = vm.eval(
- "local ok, err = pcall(function() return plugins['get']('web') end)\n\
- assert(not ok, 'the old global is not installed')\n\
- return type(packs) == 'table', plugins == nil, tostring(err)",
- );
- assert!(installed, "the packs table is installed");
- assert!(gone, "no plugins global is installed");
- assert!(
- error.contains("attempt to index a nil value"),
- "a script still calling plugins.* fails on the nil global: {error}"
- );
-}
-
-#[test]
-fn a_tool_objects_pack_is_its_packs_object_and_offering_the_pack_scopes_its_tools() {
- let vm = lua_over(pack_set());
- let same: bool = vm.eval(
- "packs.offer('web')\n\
- return tools.get('web/search').pack == packs.get('web')",
+ result,
+ (2, true, true, true),
+ "a Pack's tools are its shared tool objects, in id order, in a new array per read"
);
- assert!(same, "a tool object's pack is its Pack's object");
assert_eq!(
scoped(&vm),
["web_fetch", "web_search"],
- "offering a Pack scopes each of its tools"
+ "tools.offer takes a Pack's tools array"
);
}
#[test]
-fn offer_records_each_pack_once_from_a_name_an_object_or_a_list() {
- let vm = lua_over(pack_set());
- vm.exec(
- "packs.offer('gh')\n\
- packs.offer(packs.get('alpha'))\n\
- packs.offer({ 'gh', packs.get('web') })\n\
- packs.offer(packs.required())\n\
- packs.offer({})\n\
- assert(select('#', packs.offer('gh')) == 0, 'the verb returns nothing')",
+fn every_tool_objects_pack_is_its_packs_object() {
+ let vm = lua_over(offer_set());
+ let mismatched: String = vm.eval(
+ "local bad, walked = {}, 0\n\
+ for _, pack in ipairs(tools.packs) do\n\
+ for _, tool in ipairs(pack.tools) do\n\
+ walked = walked + 1\n\
+ if tool.pack ~= pack or tool.pack.name ~= tool.id:match('^[^/]+') then\n\
+ bad[#bad + 1] = tool.id\n\
+ end\n\
+ end\n\
+ end\n\
+ assert(walked == 5, 'every tool is walked')\n\
+ return table.concat(bad, ',')",
);
assert_eq!(
- offered_packs(&vm),
- ["gh", "alpha", "web", "mail"],
- "each Pack is recorded once, in first-offer order"
- );
- assert!(
- vm.tool_runtime()
- .lock()
- .expect("the runtime mutex is not poisoned")
- .added
- .is_empty(),
- "a Pack offer never records a wire name"
- );
-}
-
-#[test]
-fn offer_refuses_a_wrong_or_extra_argument_and_an_absent_pack_and_records_nothing() {
- let vm = lua_over(pack_set());
- let shape = "packs.offer takes a Pack id, a Pack object, or a list of them, got";
- let absent = "packs.offer: no Pack named \"mcp\" in this run; declare it under \
- uses: to require it, or offer it only when packs.get(\"mcp\") returns it";
- for (call, expected) in [
- ("packs.offer(nil)", format!("{shape} nil")),
- ("packs.offer()", format!("{shape} nil")),
- ("packs.offer(42)", format!("{shape} integer")),
- (
- "packs.offer(tools.get('web/fetch'))",
- format!("{shape} userdata"),
- ),
- ("packs.offer({ 'web', 42 })", format!("{shape} integer")),
- (
- "packs.offer('web/fetch')",
- format!(
- "{shape} \"web/fetch\": {}",
- PackId::parse("web/fetch").expect_err("a tool id is not a Pack id")
- ),
- ),
- (
- "packs.offer('web', 'gh')",
- "packs.offer takes one Pack or a list of them, got extra string".to_owned(),
- ),
- ("packs.offer('mcp')", absent.to_owned()),
- ("packs.offer({ 'web', 'mcp' })", absent.to_owned()),
- ] {
- let error: String = vm
- .lua()
- .load(format!(
- "local ok, err = pcall(function() {call} end)\n\
- assert(not ok, 'the call is refused')\n\
- return tostring(err)"
- ))
- .eval()
- .unwrap_or_else(|error| panic!("{call}: {error}"));
- assert!(error.contains(&expected), "{call}: {error}");
- }
- assert!(
- offered_packs(&vm).is_empty(),
- "a refused call records no Pack"
+ mismatched, "",
+ "each tool object's pack is == to its Pack's object"
);
}
#[test]
-fn the_scope_lists_section_tools_then_each_offered_packs_tools_each_name_once() {
- let vm = lua_over(pack_set());
+fn the_render_lists_each_offer_in_call_order_each_tool_once() {
+ let vm = lua_over(offer_set());
vm.exec(
"tools.offer('web/search')\n\
- packs.offer({ 'gh', 'web', 'alpha' })",
+ tools.offer({ 'gh', 'web', 'user-input' })",
);
let before = scoped(&vm);
assert_eq!(
@@ -304,35 +273,24 @@ fn the_scope_lists_section_tools_then_each_offered_packs_tools_each_name_once()
"gh_issues_list",
"gh_search",
"web_fetch",
- "alpha_zed"
+ "user-input_ask"
],
- "section tools first, then Packs in offer order with tools in id order, \
- each name at its first place"
+ "each offer in call order, a Pack's tools in id order, each tool at its first place"
);
- vm.exec("packs.offer('mail')");
+ vm.exec("tools.offer('subagents')");
assert_eq!(scoped(&vm), before, "a Pack with no tools adds nothing");
}
#[test]
-fn a_usable_roster_pack_with_no_tools_has_an_object_and_is_an_extra_in_name_order() {
- let vm = lua_over(roster_set());
- let result: (String, String, String, i64) = vm.eval(&format!(
- "{NAMES}\
- packs.offer('subagents')\n\
- local stub = packs.get('subagents')\n\
- return names(packs.required()), names(packs.extras()), stub.name, #stub.tools"
- ));
- assert_eq!(
- result,
- (
- "mail,web".to_owned(),
- "alpha,gh,subagents".to_owned(),
- "subagents".to_owned(),
- 0
- ),
- "a usable Pack with no tools is an extra once, beside the ones with tools"
+fn a_usable_roster_pack_with_no_tools_has_an_object_and_is_an_extra() {
+ let vm = lua_over(offer_set());
+ let result: (String, i64, bool) = vm.eval(
+ "tools.offer('subagents')\n\
+ local stub = tools.packs.get('subagents')\n\
+ return stub.name, #stub.tools, stub.required",
);
- assert_eq!(offered_packs(&vm), ["subagents"]);
+ assert_eq!(result, ("subagents".to_owned(), 0, false));
+ assert_eq!(offers(&vm), ["static:subagents"]);
assert!(
scoped(&vm).is_empty(),
"offering a Pack with no tools adds nothing to a round"
@@ -340,34 +298,15 @@ fn a_usable_roster_pack_with_no_tools_has_an_object_and_is_an_extra_in_name_orde
}
#[test]
-fn an_unavailable_roster_pack_reads_nil_stays_out_of_the_lists_and_offer_raises_its_reason() {
- let vm = lua_over(roster_set());
- let listed: (bool, String, String) = vm.eval(&format!(
- "{NAMES}\
- return packs.get('mcp') == nil, names(packs.required()), \
- names(packs.extras())"
- ));
- assert_eq!(
- listed,
- (true, "mail,web".to_owned(), "alpha,gh,subagents".to_owned()),
- "an unavailable Pack has no object and is in neither list"
- );
- let unavailable = "packs.offer: the mcp Pack is unavailable in this run: \
+fn an_unavailable_roster_pack_has_no_object_and_offering_it_raises_its_reason() {
+ let vm = lua_over(offer_set());
+ let missing: bool = vm.eval("return tools.packs.get('mcp') == nil");
+ assert!(missing, "an unavailable Pack has no object");
+ let unavailable = "tools.offer: the mcp Pack is unavailable in this run: \
the mcp server is down";
- for call in ["packs.offer('mcp')", "packs.offer({ 'web', 'mcp' })"] {
- let error: String = vm
- .lua()
- .load(format!(
- "local ok, err = pcall(function() {call} end)\n\
- assert(not ok, 'the call is refused')\n\
- return tostring(err)"
- ))
- .eval()
- .unwrap_or_else(|error| panic!("{call}: {error}"));
+ for call in ["tools.offer('mcp')", "tools.offer({ 'web', 'mcp' })"] {
+ let error = raised(&vm, call);
assert!(error.contains(unavailable), "{call}: {error}");
}
- assert!(
- offered_packs(&vm).is_empty(),
- "a refused call records no Pack"
- );
+ assert!(offers(&vm).is_empty(), "a refused call records no Pack");
}
diff --git a/crates/runvil-internal/lua/src/packs.rs b/crates/runvil-internal/lua/src/packs.rs
index 587a1ffcc..b215f1e1f 100644
--- a/crates/runvil-internal/lua/src/packs.rs
+++ b/crates/runvil-internal/lua/src/packs.rs
@@ -1,50 +1,93 @@
-//! The `packs` table: one read-only object per Pack the run knows.
+//! Pack objects and `tools.packs`: one read-only object per Pack the run
+//! knows, and the adhoc Pack every section VM holds.
//!
//! A Pack the frontmatter declares and a Pack the roster lists as able
//! to serve have an object even when they offer no tool, and every other
//! Pack has one when it offers a tool. A Pack the roster lists as
-//! unable to serve has none, and offering it raises its reason. The objects
-//! are built once per VM, after the tool objects, so `packs.required()`,
-//! `packs.extras()`, `packs.get`, and a tool object's `pack` getter
-//! hand out the same userdata for a Pack, while each list call builds a
-//! fresh array. A Pack object's `tools` reads the shared tool objects,
-//! so it passes straight to `tools.offer`. `packs.offer` puts every tool
-//! of a Pack in the section's scope, recording the Pack's name rather
-//! than its tools' wire names, until the section's first loop round
-//! renders its tool list.
+//! unable to serve has none, and offering it raises its reason. The adhoc
+//! Pack, `adhoc`, has an object in every VM; its `tools` lists the adhoc
+//! tools defined so far. The objects are built once per VM, after the tool
+//! objects, so `tools.packs.get`, the integer keys of `tools.packs`,
+//! `tools.packs.extras()`, and a tool object's `pack` getter hand out the
+//! same userdata for a Pack, while each list read builds a fresh array. A
+//! Pack object's `tools` reads the shared tool objects, so it passes
+//! straight to `tools.offer`.
+//!
+//! `tools.packs` is an empty proxy with a protected metatable: integer
+//! keys, `#`, and `pairs` walk the Pack objects in name order, `get` and
+//! `extras` are its only other members, and every write raises.
use std::collections::BTreeMap;
-use std::sync::{Arc, Mutex};
use mlua::{
- AnyUserData, Lua, MetaMethod, Table, UserData, UserDataFields, UserDataMethods, Value, Variadic,
+ AnyUserData, Lua, MetaMethod, MultiValue, Table, UserData, UserDataFields, UserDataMethods,
+ Value,
};
use runvil_types::packs::PackId;
use crate::error::{Error, Result};
use crate::handles::ToolSet;
-use crate::messages::MessageList;
-use crate::scope::ToolRuntime;
-use crate::tools::{refuse_after_render, tool_object};
+use crate::tools::tool_object;
+use crate::vm::AdhocTools;
+
+/// The id of the adhoc Pack, which holds every tool `tools.adhoc` defines.
+pub(crate) const ADHOC_PACK: &str = "adhoc";
/// The registry key of the VM's Pack-object table, keyed by name.
const PACK_OBJECTS_REGISTRY: &str = "runvil.packs.objects";
-/// One Pack as Lua sees it: `name`, and `tools`, which reads a fresh
-/// array of the Pack's tool objects in id order.
-#[derive(Debug, Clone, PartialEq, Eq)]
+/// The label `getmetatable(tools.packs)` returns, which also protects the
+/// metatable from `setmetatable`.
+const PACKS_LABEL: &str = "tools.packs is read-only";
+
+/// Whether `pack` is the adhoc Pack.
+pub(crate) fn is_adhoc(pack: &PackId) -> bool {
+ pack.to_string() == ADHOC_PACK
+}
+
+/// Where a Pack object's `tools` come from.
+#[derive(Debug, Clone)]
+enum PackTools {
+ /// A catalog Pack's offered tools, by id, in id order.
+ Catalog(Vec),
+ /// The VM's adhoc tools, read on each `tools` read.
+ Adhoc(AdhocTools),
+}
+
+/// One Pack as Lua sees it: `name`; `tools`, which reads a fresh array of
+/// the Pack's tool objects in id order; and `required`, whether the
+/// frontmatter declares it under `uses:`.
+#[derive(Debug, Clone)]
pub(crate) struct LuaPackHandle {
name: PackId,
- /// The ids of the Pack's offered tools, in id order.
- tools: Vec,
+ required: bool,
+ tools: PackTools,
+}
+
+impl LuaPackHandle {
+ /// The Pack's id, which the object stands for.
+ #[must_use]
+ pub(crate) fn name(&self) -> &PackId {
+ &self.name
+ }
}
impl UserData for LuaPackHandle {
fn add_fields>(fields: &mut F) {
fields.add_field_method_get("name", |_, this| Ok(this.name.to_string()));
+ fields.add_field_method_get("required", |_, this| Ok(this.required));
fields.add_field_method_get("tools", |lua, this| {
+ let ids = match &this.tools {
+ PackTools::Catalog(ids) => ids.clone(),
+ PackTools::Adhoc(adhoc) => adhoc
+ .bindings()
+ .map_err(mlua::Error::external)?
+ .iter()
+ .map(|binding| binding.id().to_string())
+ .collect(),
+ };
let objects = lua.create_table()?;
- for id in &this.tools {
+ for id in &ids {
if let Some(object) = tool_object(lua, id)? {
objects.raw_push(object)?;
}
@@ -65,7 +108,7 @@ impl UserData for LuaPackHandle {
}
}
-/// The VM's Pack object for `name`, read by `packs.get` and by a tool
+/// The VM's Pack object for `name`, read by `tools.packs` and by a tool
/// object's `pack` getter, or `None` for a Pack the run does not know.
///
/// # Errors
@@ -81,161 +124,146 @@ pub(crate) fn pack_object(lua: &Lua, name: &str) -> mlua::Result,
+ extras: Vec,
+}
+
+/// Builds one Pack object per declared Pack, per usable roster Pack, per
+/// other Pack with offered tools, and the adhoc Pack over `adhoc`, and
+/// returns their names.
///
/// # Errors
-/// Returns [`Error::LuaRuntime`] if an object or function cannot be created or installed.
-pub(crate) fn install_packs(
+/// Returns [`Error::LuaRuntime`] if an object cannot be created or stored.
+pub(crate) fn install_pack_objects(
lua: &Lua,
- globals: &Table,
- set: &Arc,
- runtime: &Arc>,
- list: &MessageList,
-) -> Result<()> {
+ set: &ToolSet,
+ adhoc: &AdhocTools,
+) -> Result {
let objects = lua.create_table().map_err(Error::lua)?;
- let (mut required, mut extras) = (Vec::new(), Vec::new());
- for (name, tools) in pack_tools(set) {
+ let mut names = PackNames {
+ all: Vec::new(),
+ extras: Vec::new(),
+ };
+ for (name, tools) in pack_tools(set, adhoc) {
let key = name.to_string();
- if set.declared().contains(&name) {
- required.push(key.clone());
- } else {
- extras.push(key.clone());
+ let required = set.declared().contains(&name);
+ if !required && !matches!(tools, PackTools::Adhoc(_)) {
+ names.extras.push(key.clone());
}
+ names.all.push(key.clone());
let object = lua
- .create_userdata(LuaPackHandle { name, tools })
+ .create_userdata(LuaPackHandle {
+ name,
+ required,
+ tools,
+ })
.map_err(Error::lua)?;
objects.raw_set(key, object).map_err(Error::lua)?;
}
lua.set_named_registry_value(PACK_OBJECTS_REGISTRY, objects)
.map_err(Error::lua)?;
+ Ok(names)
+}
- let table = lua.create_table().map_err(Error::lua)?;
- for (function, names) in [("required", required), ("extras", extras)] {
- let list = lua
- .create_function(move |lua, ()| {
- let objects = lua.create_table()?;
- for name in &names {
- if let Some(object) = pack_object(lua, name)? {
- objects.raw_push(object)?;
- }
- }
- Ok(objects)
- })
- .map_err(Error::lua)?;
- table.set(function, list).map_err(Error::lua)?;
- }
+/// Installs `tools.packs` on `tools` over the Pack objects `names` lists.
+///
+/// # Errors
+/// Returns [`Error::LuaRuntime`] if a function or table cannot be created
+/// or installed.
+pub(crate) fn install_pack_list(lua: &Lua, tools: &Table, names: PackNames) -> Result<()> {
+ let PackNames { all, extras } = names;
let get = lua
.create_function(|lua, name: Value| match name {
Value::String(name) => pack_object(lua, &name.to_str()?),
other => Err(mlua::Error::external(format!(
- "packs.get takes a Pack id, got {}",
+ "tools.packs.get takes one Pack id, got {}",
other.type_name()
))),
})
.map_err(Error::lua)?;
- table.set("get", get).map_err(Error::lua)?;
- install_offer(lua, &table, set, runtime, list)?;
- globals.raw_set("packs", table).map_err(Error::lua)
-}
+ let extras = lua
+ .create_function(move |lua, ()| pack_array(lua, &extras))
+ .map_err(Error::lua)?;
-/// Installs `packs.offer(pack)` and its array form: each Pack enters
-/// the section's scope once, by name, in first-offer order.
-fn install_offer(
- lua: &Lua,
- table: &Table,
- set: &Arc,
- runtime: &Arc>,
- list: &MessageList,
-) -> Result<()> {
- let set = Arc::clone(set);
- let state = Arc::clone(runtime);
- let list = list.clone();
- let offer = lua
- .create_function(move |lua, args: Variadic| {
- refuse_after_render("packs.offer", &list)?;
- let names = pack_names(lua, &set, args)?;
- let mut state = state
- .lock()
- .map_err(|_| mlua::Error::external("tool declaration runtime was poisoned"))?;
- for name in names {
- if !state.packs.contains(&name) {
- state.packs.push(name);
- }
+ let meta = lua.create_table().map_err(Error::lua)?;
+ let indexed = all.clone();
+ let index = lua
+ .create_function(move |lua, (_, key): (Table, Value)| match key {
+ Value::String(name) if name == "get" => Ok(Value::Function(get.clone())),
+ Value::String(name) if name == "extras" => Ok(Value::Function(extras.clone())),
+ key => match position(&key).and_then(|index| indexed.get(index)) {
+ Some(name) => Ok(pack_object(lua, name)?.map_or(Value::Nil, Value::UserData)),
+ None => Ok(Value::Nil),
+ },
+ })
+ .map_err(Error::lua)?;
+ meta.raw_set("__index", index).map_err(Error::lua)?;
+ let count = all.len();
+ let len = lua
+ .create_function(move |_, _: MultiValue| Ok(count))
+ .map_err(Error::lua)?;
+ meta.raw_set("__len", len).map_err(Error::lua)?;
+ let step = lua
+ .create_function(move |lua, (_, key): (Value, Value)| {
+ let next = match key {
+ Value::Nil => 0,
+ key => position(&key).map_or(all.len(), |index| index + 1),
+ };
+ match all.get(next) {
+ Some(name) => Ok((
+ Value::Integer(i64::try_from(next + 1).unwrap_or(i64::MAX)),
+ pack_object(lua, name)?.map_or(Value::Nil, Value::UserData),
+ )),
+ None => Ok((Value::Nil, Value::Nil)),
}
- Ok(())
})
.map_err(Error::lua)?;
- table.set("offer", offer).map_err(Error::lua)
+ let pairs = lua
+ .create_function(move |_, proxy: Table| Ok((step.clone(), proxy, Value::Nil)))
+ .map_err(Error::lua)?;
+ meta.raw_set("__pairs", pairs).map_err(Error::lua)?;
+ let newindex = lua
+ .create_function(|_, _: MultiValue| -> mlua::Result<()> {
+ Err(mlua::Error::external(PACKS_LABEL))
+ })
+ .map_err(Error::lua)?;
+ meta.raw_set("__newindex", newindex).map_err(Error::lua)?;
+ meta.raw_set("__metatable", PACKS_LABEL)
+ .map_err(Error::lua)?;
+
+ let proxy = lua.create_table().map_err(Error::lua)?;
+ proxy.set_metatable(Some(meta)).map_err(Error::lua)?;
+ tools.raw_set("packs", proxy).map_err(Error::lua)
}
-/// Reads `packs.offer`'s one argument, a Pack id, a Pack object,
-/// or an array of either, as the names of Packs the run knows, checking
-/// every entry against `set`'s roster before returning any.
-fn pack_names(lua: &Lua, set: &ToolSet, args: Variadic) -> mlua::Result> {
- let mut args = args.into_iter();
- let target = args.next().unwrap_or(Value::Nil);
- if let Some(extra) = args.next() {
- return Err(mlua::Error::external(format!(
- "packs.offer takes one Pack or a list of them, got extra {}",
- extra.type_name()
- )));
- }
- match target {
- Value::Table(list) => list
- .sequence_values::()
- .map(|entry| pack_name(lua, set, &entry?))
- .collect(),
- single => Ok(vec![pack_name(lua, set, &single)?]),
+/// The 0-based position an integer key of `tools.packs` names, or `None`
+/// for any other key.
+fn position(key: &Value) -> Option {
+ match key {
+ Value::Integer(index) => usize::try_from(*index).ok()?.checked_sub(1),
+ _ => None,
}
}
-/// Reads one name or Pack object as the name of a Pack the run knows,
-/// raising the roster's reason for a Pack that can't serve the run.
-fn pack_name(lua: &Lua, set: &ToolSet, value: &Value) -> mlua::Result {
- let rejected = |found: String| {
- mlua::Error::external(format!(
- "packs.offer takes a Pack id, a Pack object, or a list of them, got {found}"
- ))
- };
- match value {
- Value::String(text) => {
- let text = text.to_string_lossy();
- let name = match PackId::parse(&text) {
- Ok(name) => name,
- Err(error) => return Err(rejected(format!("{text:?}: {error}"))),
- };
- if let Some(Some(reason)) = set.roster().get(&name) {
- return Err(mlua::Error::external(format!(
- "packs.offer: the {name} Pack is unavailable in this run: {reason}"
- )));
- }
- if pack_object(lua, &text)?.is_none() {
- return Err(mlua::Error::external(format!(
- "packs.offer: no Pack named {text:?} in this run; declare it under \
- uses: to require it, or offer it only when packs.get({text:?}) \
- returns it"
- )));
- }
- Ok(name)
+/// A fresh array of the Pack objects `names` lists, in order.
+fn pack_array(lua: &Lua, names: &[String]) -> mlua::Result
{
+ let objects = lua.create_table()?;
+ for name in names {
+ if let Some(object) = pack_object(lua, name)? {
+ objects.raw_push(object)?;
}
- Value::UserData(object) => object
- .borrow::()
- .map(|handle| handle.name.clone())
- .map_err(|_| rejected(value.type_name().to_owned())),
- other => Err(rejected(other.type_name().to_owned())),
}
+ Ok(objects)
}
-/// Each Pack the run knows, in id order, with the ids of its offered
-/// tools in the set's id order: every declared Pack, each roster Pack
-/// that can serve, with or without tools, and every other Pack that
-/// offers one.
-fn pack_tools(set: &ToolSet) -> BTreeMap> {
+/// Each Pack the run knows, in id order, with its tools: every declared
+/// Pack, each roster Pack that can serve, with or without tools, and every
+/// other Pack that offers one, each with its offered tools' ids in the
+/// set's id order, and the adhoc Pack over `adhoc`.
+fn pack_tools(set: &ToolSet, adhoc: &AdhocTools) -> BTreeMap {
let usable = set
.roster()
.iter()
@@ -253,6 +281,13 @@ fn pack_tools(set: &ToolSet) -> BTreeMap> {
.or_default()
.push(binding.id().to_string());
}
+ let mut packs: BTreeMap = packs
+ .into_iter()
+ .map(|(name, ids)| (name, PackTools::Catalog(ids)))
+ .collect();
+ if let Ok(name) = PackId::parse(ADHOC_PACK) {
+ packs.insert(name, PackTools::Adhoc(adhoc.clone()));
+ }
packs
}
diff --git a/crates/runvil-internal/lua/src/protocol.rs b/crates/runvil-internal/lua/src/protocol.rs
index c6c31806b..7eaacd760 100644
--- a/crates/runvil-internal/lua/src/protocol.rs
+++ b/crates/runvil-internal/lua/src/protocol.rs
@@ -36,4 +36,4 @@ pub use parse::YieldParse;
pub(crate) use parse::parse_record;
pub use record::{ContentPart, MessageContent, MessageRecord, RecordRole, ToolCallRecord};
pub(crate) use render::Retained;
-pub use request::{LocalToolOutcome, Request, SpawnVia, VfsOp};
+pub use request::{AdhocToolOutcome, Request, SpawnVia, VfsOp};
diff --git a/crates/runvil-internal/lua/src/protocol/answer.rs b/crates/runvil-internal/lua/src/protocol/answer.rs
index 1c16ec96a..036c0793c 100644
--- a/crates/runvil-internal/lua/src/protocol/answer.rs
+++ b/crates/runvil-internal/lua/src/protocol/answer.rs
@@ -1,10 +1,10 @@
//! The answer vocabulary: one dispatched request's outcome and the payload
//! types its variants hold.
//!
-//! A local tool call is answered in two steps. The `tool_call` request's
-//! answer is [`ToolCallOutcome::Local`], which resumes the shim with the
+//! An adhoc tool call is answered in two steps. The `tool_call` request's
+//! answer is [`ToolCallOutcome::Adhoc`], which resumes the shim with the
//! handler itself so the shim runs it inside the calling coroutine. The
-//! shim then yields `local_tool_done` with the handler's result, and that
+//! shim then yields `adhoc_tool_done` with the handler's result, and that
//! request's answer is an ordinary [`Answer::ToolCallResult`]: the text
//! on success, the error for a rejected return.
@@ -53,12 +53,13 @@ pub enum ToolCallOutcome {
Plain(String),
/// A structured binding's parsed JSON output, resumed as a Lua table.
Structured(serde_json::Value),
- /// A local Lua tool's call, resumed as `(true, nil, handler, args)`:
- /// the handler registered under `alias` and a fresh table converted
- /// from `args`, so the shim runs the handler inside the calling
- /// coroutine and reports how it ended with a `local_tool_done` yield.
- Local {
- /// The local tool's alias, naming its handler.
+ /// An adhoc tool's call, resumed as `(true, nil, handler, args)`:
+ /// the handler `tools.adhoc` registered under the wire name `alias`
+ /// and a fresh table converted from `args`, so the shim runs the
+ /// handler inside the calling coroutine and reports how it ended with
+ /// an `adhoc_tool_done` yield.
+ Adhoc {
+ /// The adhoc tool's wire name, naming its handler.
alias: String,
/// The call's JSON arguments.
args: serde_json::Value,
diff --git a/crates/runvil-internal/lua/src/protocol/parse.rs b/crates/runvil-internal/lua/src/protocol/parse.rs
index 3baead3eb..9f8daf033 100644
--- a/crates/runvil-internal/lua/src/protocol/parse.rs
+++ b/crates/runvil-internal/lua/src/protocol/parse.rs
@@ -20,7 +20,7 @@ use tasks::{
parse_cancel, parse_concurrency, parse_join_any, parse_note, parse_ready, parse_spawn,
parse_status, parse_timer,
};
-use tools::{parse_local_tool_done, parse_tool_call, parse_tool_calls};
+use tools::{parse_adhoc_tool_done, parse_tool_call, parse_tool_calls};
use crate::error::{Error, Result};
use crate::handles::resolve_section_target;
@@ -233,7 +233,7 @@ impl Request {
"tool_calls" => classify(parse_tool_calls(lua, table), |error| {
Answer::ToolCallsResult(Err(error))
}),
- "local_tool_done" => match parse_local_tool_done(table) {
+ "adhoc_tool_done" => match parse_adhoc_tool_done(table) {
Some(request) => YieldParse::Request(request),
None => YieldParse::Malformed(direct_yield_error()),
},
diff --git a/crates/runvil-internal/lua/src/protocol/parse/tools.rs b/crates/runvil-internal/lua/src/protocol/parse/tools.rs
index f5d1048b1..c889d3db0 100644
--- a/crates/runvil-internal/lua/src/protocol/parse/tools.rs
+++ b/crates/runvil-internal/lua/src/protocol/parse/tools.rs
@@ -1,10 +1,10 @@
//! The tool request parsers: a `tools.call`, the loop's batched
-//! `tool_calls`, and a local tool's `local_tool_done`.
+//! `tool_calls`, and an adhoc tool's `adhoc_tool_done`.
use mlua::{Lua, LuaSerdeExt, MultiValue, Value};
-use crate::protocol::{LocalToolOutcome, Request, ToolCallRecord};
-use crate::tools::tool_name;
+use crate::protocol::{AdhocToolOutcome, Request, ToolCallRecord};
+use crate::tools::{model_tool_name, tool_name};
use crate::vm::scalar_return;
use super::{FieldFailure, call_error, shim_optional_string, shim_optional_u32};
@@ -37,26 +37,36 @@ pub(super) fn parse_tool_call(
})
}
-/// Reads a `tool_call` table: the author-supplied `alias` (a string or a
-/// Tool object, decoded through the one alias-or-Tool polymorphism) and
-/// `args`, plus the shim-produced optional `call_id` and `turn`.
+/// Reads a `tool_call` table: the `alias` naming the tool and the
+/// author-supplied `args`, plus the shim-produced optional `call_id` and
+/// `turn`.
///
-/// An absent or nil `args` parses as the empty object (the empty-argument
-/// call every tool accepts). A non-table or JSON-unrepresentable `args` is
-/// the call's error, framed as the other author-argument failures are,
-/// so an author `pcall` catches it at the call site. `call_id` is set only
-/// by the loop shim for a model-issued call, so a present non-string is a
-/// malformed yield rather than a call error; `turn`, set by the same shim,
-/// is likewise malformed unless it is an integer within `u32` range.
+/// A script call, with no `call_id`, names its tool by id or tool object,
+/// decoded through the one id-or-tool polymorphism; a model-issued call
+/// names it by the wire name the model sent. An absent or nil `args`
+/// parses as the empty object (the empty-argument call every tool
+/// accepts). A wrong `alias` for a script call, or a non-table or
+/// JSON-unrepresentable `args`, is the call's error, framed as the other
+/// author-argument failures are, so an author `pcall` catches it at the
+/// call site. `call_id` is set only by the loop shim for a model-issued
+/// call, so a present non-string is a malformed yield rather than a call
+/// error; `turn`, set by the same shim, is likewise malformed unless it is
+/// an integer within `u32` range.
fn read_tool_call(
lua: &Lua,
table: &mlua::Table,
) -> std::result::Result {
+ let call_id = shim_optional_string(table, "call_id")?;
+ let decode = if call_id.is_some() {
+ model_tool_name
+ } else {
+ tool_name
+ };
let alias = match table.raw_get::("alias") {
// Flatten to the call-error string so the answer frames exactly as
// the other author-argument failures (`Error::Lua`, not a runtime
// wrapper).
- Ok(value) => tool_name(&value).map_err(|error| call_error(error.to_string()))?,
+ Ok(value) => decode(&value).map_err(|error| call_error(error.to_string()))?,
Err(_) => return Err(FieldFailure::Malformed),
};
let args = match table.raw_get::("args") {
@@ -77,7 +87,6 @@ fn read_tool_call(
}
Err(_) => return Err(FieldFailure::Malformed),
};
- let call_id = shim_optional_string(table, "call_id")?;
let turn = shim_optional_u32(table, "turn")?;
Ok(ToolCallFields {
alias,
@@ -106,6 +115,9 @@ pub(super) fn parse_tool_calls(
let Ok(Value::Table(entry)) = entries.raw_get::(index) else {
return Err(FieldFailure::Malformed);
};
+ if shim_optional_string(&entry, "call_id")?.is_none() {
+ return Err(FieldFailure::Malformed);
+ }
let ToolCallFields {
alias,
args,
@@ -125,22 +137,22 @@ pub(super) fn parse_tool_calls(
Ok(Request::ToolCalls { calls, turn })
}
-/// Parses a `local_tool_done` request: the shim-produced `ok` flag and,
+/// Parses an `adhoc_tool_done` request: the shim-produced `ok` flag and,
/// when the handler returned, its first return value as `value`. A
/// returned value takes the scalar-return rule a block's return takes, so
-/// nil reads as `""` and a table is a [`LocalToolOutcome::BadReturn`].
+/// nil reads as `""` and a table is an [`AdhocToolOutcome::BadReturn`].
/// `None` for a missing or non-boolean `ok`.
-pub(super) fn parse_local_tool_done(table: &mlua::Table) -> Option {
+pub(super) fn parse_adhoc_tool_done(table: &mlua::Table) -> Option {
let outcome = match table.raw_get::("ok").ok()? {
Value::Boolean(true) => {
let value = table.raw_get::("value").ok()?;
match scalar_return(MultiValue::from_vec(vec![value])) {
- Ok(text) => LocalToolOutcome::Returned(text.unwrap_or_default()),
- Err(error) => LocalToolOutcome::BadReturn(error),
+ Ok(text) => AdhocToolOutcome::Returned(text.unwrap_or_default()),
+ Err(error) => AdhocToolOutcome::BadReturn(error),
}
}
- Value::Boolean(false) => LocalToolOutcome::Raised,
+ Value::Boolean(false) => AdhocToolOutcome::Raised,
_ => return None,
};
- Some(Request::LocalToolDone { outcome })
+ Some(Request::AdhocToolDone { outcome })
}
diff --git a/crates/runvil-internal/lua/src/protocol/render.rs b/crates/runvil-internal/lua/src/protocol/render.rs
index 79eb2b5e6..9f8934f4a 100644
--- a/crates/runvil-internal/lua/src/protocol/render.rs
+++ b/crates/runvil-internal/lua/src/protocol/render.rs
@@ -4,7 +4,7 @@
use mlua::{Lua, LuaSerdeExt, MultiValue, Table, Value};
use crate::error_value::{ErrorValue, error_table};
-use crate::tools::local_handler;
+use crate::tools::adhoc_handler;
use super::answer::{Answer, TaskDelivery, TaskStatus, ToolCallOutcome, VfsOutcome};
@@ -141,11 +141,11 @@ impl Answer {
vec![lua.to_value(&json)?]
}
// The result slot stays nil: the handler and its arguments ride
- // after it, so the shim tells a local answer from a bound
+ // after it, so the shim tells an adhoc answer from a bound
// result by the handler's presence.
- Answer::ToolCallResult(Ok(ToolCallOutcome::Local { alias, args })) => vec![
+ Answer::ToolCallResult(Ok(ToolCallOutcome::Adhoc { alias, args })) => vec![
Value::Nil,
- Value::Function(local_handler(lua, &alias)?),
+ Value::Function(adhoc_handler(lua, &alias)?),
lua.to_value(&args)?,
],
Answer::ToolCallsResult(Ok(texts)) => {
diff --git a/crates/runvil-internal/lua/src/protocol/request.rs b/crates/runvil-internal/lua/src/protocol/request.rs
index e0a3ab0c4..d856b457e 100644
--- a/crates/runvil-internal/lua/src/protocol/request.rs
+++ b/crates/runvil-internal/lua/src/protocol/request.rs
@@ -2,11 +2,11 @@
//! yield and the store operations they hold. The message-record types the
//! chat request is built from are in `record`.
//!
-//! A local tool call spans two requests. The first is the ordinary
+//! An adhoc tool call spans two requests. The first is the ordinary
//! [`Request::ToolCall`], which the scheduler answers with the handler.
//! The shim runs the handler inside the calling coroutine, so any
//! suspending call the handler makes is a request of its own, and then
-//! yields [`Request::LocalToolDone`] with how the handler ended, so the
+//! yields [`Request::AdhocToolDone`] with how the handler ended, so the
//! scheduler can report the call and answer it.
use std::num::NonZeroU64;
@@ -136,10 +136,11 @@ pub enum Request {
/// The task to cancel.
task: TaskId,
},
- /// `tools.call(alias_or_tool, args)`: suspending dispatch of a bound
- /// tool through the shared dispatch function.
+ /// `tools.call(id_or_tool, args)`: suspending dispatch of a tool
+ /// through the shared dispatch function.
ToolCall {
- /// The author-supplied prompt-local tool alias.
+ /// The tool a script names by id, or the wire name a model-issued
+ /// call names.
alias: String,
/// The author-supplied JSON arguments; an absent or nil `args`
/// parses as the empty object.
@@ -161,7 +162,7 @@ pub enum Request {
},
/// The unanswered calls of one model round, yielded by the loop's
/// step: the scheduler issues every catalog call up to the first call
- /// that must run alone (a local tool) and answers
+ /// that must run alone (an adhoc tool) and answers
/// once each issued call has landed, with one text per issued call in
/// call order. The loop sends the call it stopped at as an ordinary
/// [`Request::ToolCall`]. Shim-produced in every field, so a wrong
@@ -172,20 +173,20 @@ pub enum Request {
/// The turn of the chat round that requested the calls.
turn: u32,
},
- /// The second yield of a local tool call: the shim ran the handler the
+ /// The second yield of an adhoc tool call: the shim ran the handler the
/// `tool_call` answer handed it and reports how the handler ended.
/// Shim-produced in every field, so a wrong shape is a malformed
/// yield, never an error at the author's call site.
- LocalToolDone {
+ AdhocToolDone {
/// How the handler ended.
- outcome: LocalToolOutcome,
+ outcome: AdhocToolOutcome,
},
/// One stateless tool-capable model round over the section's list,
/// yielded by the `models.loop` shim once per round. The dispatch arm
/// first refuses an empty list; the round sends the section's
/// rendered tool list, which the dispatch arm renders from the
- /// section's tool scope, local Lua tools included, at the first round
- /// to reach the build and attaches to the list.
+ /// section's offers at the first round to reach the build and
+ /// attaches to the list.
Chat {
/// The list the round sends, which may be empty, since the
/// dispatch, not the parse, refuses an empty list. Its records
@@ -208,10 +209,10 @@ pub enum Request {
},
}
-/// How a local tool's handler ended, as its `local_tool_done` yield
+/// How an adhoc tool's handler ended, as its `adhoc_tool_done` yield
/// reports it.
#[derive(Debug)]
-pub enum LocalToolOutcome {
+pub enum AdhocToolOutcome {
/// The handler returned: its first return value as text under the
/// scalar-return rule, `""` for nil.
Returned(String),
diff --git a/crates/runvil-internal/lua/src/protocol/tests/answer.rs b/crates/runvil-internal/lua/src/protocol/tests/answer.rs
index 0363696e0..a6a435c12 100644
--- a/crates/runvil-internal/lua/src/protocol/tests/answer.rs
+++ b/crates/runvil-internal/lua/src/protocol/tests/answer.rs
@@ -160,32 +160,32 @@ fn an_ok_structured_tool_call_answer_round_trips_as_a_table() {
assert_eq!(images_len, 0);
}
-/// A fresh VM with the `tools` namespace installed and one local tool,
-/// `grab`, registered through `tools.offer_local`.
-fn lua_with_local_grab() -> Lua {
+/// A fresh VM with the `tools` namespace installed and one adhoc tool,
+/// `grab`, defined through `tools.adhoc`.
+fn lua_with_adhoc_grab() -> Lua {
let lua = Lua::new();
crate::tools::install_tools(
&lua,
&lua.globals(),
&std::sync::Arc::new(crate::ToolSet::default()),
&std::sync::Arc::new(std::sync::Mutex::new(crate::ToolRuntime::default())),
- &crate::vm::LocalTools::default(),
+ &crate::vm::AdhocTools::default(),
&crate::MessageList::default(),
)
.expect("the tools install cannot fail on a fresh VM");
lua.load(
- "tools.offer_local('grab', 'Grab a value', { value = 'string' }, \
- function(args) return 'got ' .. args.value end)",
+ "tools.adhoc({ name = 'grab', description = 'Grab a value', \
+ parameters = { value = 'string' } }, function(args) return 'got ' .. args.value end)",
)
.exec()
- .expect("the local tool registers");
+ .expect("the adhoc tool registers");
lua
}
#[test]
-fn a_local_tool_call_answer_resumes_with_its_handler_and_args() {
- let lua = lua_with_local_grab();
- let (envelope, retained) = Answer::::ToolCallResult(Ok(ToolCallOutcome::Local {
+fn an_adhoc_tool_call_answer_resumes_with_its_handler_and_args() {
+ let lua = lua_with_adhoc_grab();
+ let (envelope, retained) = Answer::::ToolCallResult(Ok(ToolCallOutcome::Adhoc {
alias: "grab".to_owned(),
args: json!({ "value": "hi" }),
}))
@@ -202,16 +202,16 @@ fn a_local_tool_call_answer_resumes_with_its_handler_and_args() {
assert!(ok);
assert!(
result_is_nil,
- "the result slot stays nil for a local answer"
+ "the result slot stays nil for an adhoc answer"
);
assert!(handler_is_fn, "the handler resumes as a function");
assert_eq!(called, "got hi", "the registered handler runs on the args");
}
#[test]
-fn a_local_tool_call_answer_for_an_unregistered_alias_is_an_error() {
- let lua = lua_with_local_grab();
- let error = Answer::::ToolCallResult(Ok(ToolCallOutcome::Local {
+fn an_adhoc_tool_call_answer_for_an_unregistered_alias_is_an_error() {
+ let lua = lua_with_adhoc_grab();
+ let error = Answer::::ToolCallResult(Ok(ToolCallOutcome::Adhoc {
alias: "missing".to_owned(),
args: json!({}),
}))
@@ -220,7 +220,7 @@ fn a_local_tool_call_answer_for_an_unregistered_alias_is_an_error() {
assert!(
error
.to_string()
- .contains("a local tool answer names a registered handler"),
+ .contains("an adhoc tool answer names a registered handler"),
"the error names the broken invariant: {error}"
);
}
diff --git a/crates/runvil-internal/lua/src/protocol/tests/parse.rs b/crates/runvil-internal/lua/src/protocol/tests/parse.rs
index d76e23a81..b33d12a2f 100644
--- a/crates/runvil-internal/lua/src/protocol/tests/parse.rs
+++ b/crates/runvil-internal/lua/src/protocol/tests/parse.rs
@@ -1,5 +1,5 @@
//! Yield-to-request parsing for the leaf and structural requests (`infer`,
-//! `call`, `tool_calls`, `local_tool_done`), and the malformed-yield
+//! `call`, `tool_calls`, `adhoc_tool_done`), and the malformed-yield
//! rejections shared by every op. The `tool_call` request is in
//! `parse_tool_call` and the task-operation requests (`spawn`, `timer`,
//! `concurrency`) are in `parse_tasks`.
@@ -117,35 +117,35 @@ fn a_tool_calls_yield_missing_its_turn_a_table_per_call_or_a_call_id_is_a_malfor
}
}
-/// Parses a `local_tool_done` yield with `ok = true` and `value` set to
+/// Parses an `adhoc_tool_done` yield with `ok = true` and `value` set to
/// what `source` evaluates to, returning the outcome.
-fn local_tool_done_returning(lua: &Lua, source: &str) -> LocalToolOutcome {
+fn adhoc_tool_done_returning(lua: &Lua, source: &str) -> AdhocToolOutcome {
let table = lua_table(
lua,
- &format!("{{ op = 'local_tool_done', ok = true, value = {source} }}"),
+ &format!("{{ op = 'adhoc_tool_done', ok = true, value = {source} }}"),
);
match expect_request(Request::from_yield(lua, &Value::Table(table))) {
- Request::LocalToolDone { outcome } => outcome,
- other => panic!("expected a local_tool_done request, got {other:?}"),
+ Request::AdhocToolDone { outcome } => outcome,
+ other => panic!("expected an adhoc_tool_done request, got {other:?}"),
}
}
#[test]
-fn a_local_tool_done_return_becomes_its_scalar_text() {
+fn an_adhoc_tool_done_return_becomes_its_scalar_text() {
let lua = Lua::new();
for (source, expected) in [("'hi'", "hi"), ("42", "42"), ("true", "true"), ("nil", "")] {
- match local_tool_done_returning(&lua, source) {
- LocalToolOutcome::Returned(text) => assert_eq!(text, expected, "{source}"),
+ match adhoc_tool_done_returning(&lua, source) {
+ AdhocToolOutcome::Returned(text) => assert_eq!(text, expected, "{source}"),
other => panic!("{source} must return its text, got {other:?}"),
}
}
}
#[test]
-fn a_local_tool_done_table_return_is_a_bad_return() {
+fn an_adhoc_tool_done_table_return_is_a_bad_return() {
let lua = Lua::new();
- match local_tool_done_returning(&lua, "{ 1, 2 }") {
- LocalToolOutcome::BadReturn(Error::Lua(message)) => {
+ match adhoc_tool_done_returning(&lua, "{ 1, 2 }") {
+ AdhocToolOutcome::BadReturn(Error::Lua(message)) => {
assert_eq!(message, "cannot return a table as a result");
}
other => panic!("a table return must be rejected, got {other:?}"),
@@ -153,26 +153,26 @@ fn a_local_tool_done_table_return_is_a_bad_return() {
}
#[test]
-fn a_local_tool_done_with_ok_false_is_raised() {
+fn an_adhoc_tool_done_with_ok_false_is_raised() {
let lua = Lua::new();
let table = lua_table(
&lua,
- "{ op = 'local_tool_done', ok = false, value = 'ignored' }",
+ "{ op = 'adhoc_tool_done', ok = false, value = 'ignored' }",
);
match expect_request(Request::from_yield(&lua, &Value::Table(table))) {
- Request::LocalToolDone {
- outcome: LocalToolOutcome::Raised,
+ Request::AdhocToolDone {
+ outcome: AdhocToolOutcome::Raised,
} => {}
other => panic!("expected a raised outcome, got {other:?}"),
}
}
#[test]
-fn a_local_tool_done_without_a_boolean_ok_is_a_malformed_yield() {
+fn an_adhoc_tool_done_without_a_boolean_ok_is_a_malformed_yield() {
let lua = Lua::new();
for source in [
- "{ op = 'local_tool_done', value = 'hi' }",
- "{ op = 'local_tool_done', ok = 1, value = 'hi' }",
+ "{ op = 'adhoc_tool_done', value = 'hi' }",
+ "{ op = 'adhoc_tool_done', ok = 1, value = 'hi' }",
] {
let table = lua_table(&lua, source);
assert_direct_yield(Request::from_yield(&lua, &Value::Table(table)));
diff --git a/crates/runvil-internal/lua/src/protocol/tests/parse_tool_call.rs b/crates/runvil-internal/lua/src/protocol/tests/parse_tool_call.rs
index f63695ee8..45e522522 100644
--- a/crates/runvil-internal/lua/src/protocol/tests/parse_tool_call.rs
+++ b/crates/runvil-internal/lua/src/protocol/tests/parse_tool_call.rs
@@ -10,7 +10,7 @@ fn tool_call_parses_alias_and_args() {
let lua = Lua::new();
let table = lua_table(
&lua,
- "{ op = 'tool_call', alias = 'echo', args = { value = 'hi' } }",
+ "{ op = 'tool_call', alias = 'tools/echo', args = { value = 'hi' } }",
);
let request = expect_request(Request::from_yield(&lua, &Value::Table(table)));
match request {
@@ -20,7 +20,7 @@ fn tool_call_parses_alias_and_args() {
call_id,
turn,
} => {
- assert_eq!(alias, "echo");
+ assert_eq!(alias, "tools/echo");
assert_eq!(args, json!({ "value": "hi" }));
assert_eq!(call_id, None, "a script call omits the call id");
assert_eq!(turn, None, "a script call omits the turn");
@@ -111,7 +111,7 @@ fn a_turn_outside_u32_or_not_an_integer_is_a_malformed_yield() {
#[test]
fn tool_call_without_args_parses_the_empty_object() {
let lua = Lua::new();
- let table = lua_table(&lua, "{ op = 'tool_call', alias = 'echo' }");
+ let table = lua_table(&lua, "{ op = 'tool_call', alias = 'tools/echo' }");
let request = expect_request(Request::from_yield(&lua, &Value::Table(table)));
match request {
Request::ToolCall { args, .. } => assert_eq!(args, json!({})),
@@ -122,8 +122,8 @@ fn tool_call_without_args_parses_the_empty_object() {
#[test]
fn a_marked_empty_list_in_the_args_parses_to_an_empty_array() {
let vm = crate::test_vm::TestVm::new().build();
- let table: mlua::Table =
- vm.eval("return { op = 'tool_call', alias = 'echo', args = { items = json.array() } }");
+ let table: mlua::Table = vm
+ .eval("return { op = 'tool_call', alias = 'tools/echo', args = { items = json.array() } }");
match expect_request(Request::from_yield(vm.lua(), &Value::Table(table))) {
Request::ToolCall { args, .. } => assert_eq!(args, json!({ "items": [] })),
other => panic!("expected a tool_call request, got {other:?}"),
@@ -159,17 +159,34 @@ fn a_tool_call_with_a_non_alias_alias_is_the_calls_error() {
YieldParse::Call(Answer::ToolCallResult(Err(Error::Lua(message)))) => {
assert_eq!(
message,
- "tools.call takes a tool id, a local alias, or a tool object, got integer"
+ "tools.call takes a tool id or a tool object, got integer"
);
}
other => panic!("expected the alias call error, got {other:?}"),
}
}
+#[test]
+fn a_script_call_naming_a_string_without_a_slash_is_the_calls_error() {
+ // A model-issued call names its tool by wire name; a script names it
+ // by id, so a bare name is refused before any resolution.
+ let lua = Lua::new();
+ let table = lua_table(&lua, "{ op = 'tool_call', alias = 'grab' }");
+ match Request::from_yield(&lua, &Value::Table(table)) {
+ YieldParse::Call(Answer::ToolCallResult(Err(Error::Lua(message)))) => {
+ assert_eq!(message, "tools.call: \"grab\" is not a tool id");
+ }
+ other => panic!("expected the id call error, got {other:?}"),
+ }
+}
+
#[test]
fn a_tool_call_with_a_non_table_args_is_the_calls_error() {
let lua = Lua::new();
- let table = lua_table(&lua, "{ op = 'tool_call', alias = 'echo', args = 42 }");
+ let table = lua_table(
+ &lua,
+ "{ op = 'tool_call', alias = 'tools/echo', args = 42 }",
+ );
match Request::from_yield(&lua, &Value::Table(table)) {
YieldParse::Call(Answer::ToolCallResult(Err(Error::Lua(message)))) => {
assert_eq!(message, "args must be a table, got integer");
@@ -183,7 +200,7 @@ fn a_tool_call_with_an_unrepresentable_args_table_is_the_calls_error() {
let lua = Lua::new();
let table = lua_table(
&lua,
- "{ op = 'tool_call', alias = 'echo', args = { f = function() end } }",
+ "{ op = 'tool_call', alias = 'tools/echo', args = { f = function() end } }",
);
let args: Value = table
.raw_get("args")
diff --git a/crates/runvil-internal/lua/src/scope.rs b/crates/runvil-internal/lua/src/scope.rs
index d33376ce8..442a4be6c 100644
--- a/crates/runvil-internal/lua/src/scope.rs
+++ b/crates/runvil-internal/lua/src/scope.rs
@@ -1,5 +1,5 @@
-//! Per-VM tool runtime state: call counts, the scoped tool set a section
-//! sees, and the tool list its first loop round rendered from that set.
+//! Per-VM tool runtime state: call counts, the offers a section made, and
+//! the tool list its first loop round rendered from them.
use std::borrow::Cow;
use std::collections::BTreeMap;
@@ -11,9 +11,9 @@ use runvil_types::tools::ToolId;
use crate::error::{Error, Result};
-/// Shared per-VM tool-call counts, seeded at 0 for every key the installer
-/// was given: a catalog tool's id, or a local tool's alias. A dispatch
-/// seeds a missing key on demand through [`ensure`](Self::ensure).
+/// Shared per-VM tool-call counts, keyed by tool id and seeded at 0 for
+/// every id the installer was given. A dispatch seeds a missing key on
+/// demand through [`ensure`](Self::ensure).
///
/// The executor increments a count when dispatch is attempted (even if the tool
/// later errors). Lua reads the snapshot through the `tools.calls` table.
@@ -82,15 +82,70 @@ impl ToolCallCounts {
}
}
-/// Tracks the tools and Packs one section VM offered.
+/// What one offer names: a tool by id, or a Pack, whose tools the render
+/// expands.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum OfferTarget {
+ /// One tool, by id.
+ Tool(ToolId),
+ /// Every tool of a Pack, read when the section renders.
+ Pack(PackId),
+}
+
+/// Which list an offer feeds.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum OfferMode {
+ /// The rendered list, which every round of the section sends.
+ Static,
+ /// The dynamic list, stored beside the rendered list.
+ Dynamic,
+}
+
+/// One remembered offer: what it names and which list it feeds.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Offer {
+ /// What the offer names.
+ pub target: OfferTarget,
+ /// Which list the offer feeds.
+ pub mode: OfferMode,
+}
+
+/// The offers one section VM made, in call order.
#[derive(Debug, Default)]
pub struct ToolRuntime {
- /// The wire names `tools.offer` put in the section's scope, in
- /// first-offer order.
- pub added: Vec,
- /// The Packs `packs.offer` put in the section's scope, in
- /// first-offer order.
- pub packs: Vec,
+ /// Every offer, in call order, each held once.
+ pub offers: Vec,
+}
+
+impl ToolRuntime {
+ /// Remembers an offer of the tool `id` under `mode`, unless an equal
+ /// offer is already held.
+ pub fn add_tool(&mut self, id: ToolId, mode: OfferMode) {
+ self.add(OfferTarget::Tool(id), mode);
+ }
+
+ /// Remembers an offer of the Pack `pack` under `mode`, unless an equal
+ /// offer is already held.
+ pub fn add_pack(&mut self, pack: PackId, mode: OfferMode) {
+ self.add(OfferTarget::Pack(pack), mode);
+ }
+
+ fn add(&mut self, target: OfferTarget, mode: OfferMode) {
+ let offer = Offer { target, mode };
+ if !self.offers.contains(&offer) {
+ self.offers.push(offer);
+ }
+ }
+}
+
+/// One advertised tool: its id and its Pack's vendor.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Advertised {
+ /// The tool's id.
+ pub id: ToolId,
+ /// The vendor of the tool's Pack, as the caller reported it; `None`
+ /// when it reported none, and for an adhoc tool.
+ pub vendor: Option,
}
/// The tool list a section's first loop round rendered.
@@ -98,12 +153,14 @@ pub struct ToolRuntime {
pub struct RenderedTools {
/// The schemas every round of the section sends.
pub schemas: Vec,
- /// Each advertised name's catalog tool, `None` for a local tool.
+ /// Each advertised wire name's tool.
///
/// Every round copies this map onto its chain: the round's answer is
- /// gated against its keys, and the reported batch names a catalog
- /// tool's id. The `tool_call` the loop then yields resolves each name
- /// itself, a wire name against the run's offering and a local alias
- /// against the section VM's handlers.
- pub dispatch: BTreeMap>,
+ /// gated against its keys, and the reported batch names each tool's
+ /// id and vendor. A model's call is routed by the entry under its wire
+ /// name.
+ pub dispatch: BTreeMap,
+ /// The tools the section's dynamic offers named that the rendered
+ /// list leaves out, in offer order.
+ pub dynamic: Vec,
}
diff --git a/crates/runvil-internal/lua/src/test_vm.rs b/crates/runvil-internal/lua/src/test_vm.rs
index cfea5a455..88803d615 100644
--- a/crates/runvil-internal/lua/src/test_vm.rs
+++ b/crates/runvil-internal/lua/src/test_vm.rs
@@ -109,7 +109,75 @@ pub(crate) fn echo_tool() -> ToolInfo {
tool_at("tools/echo")
}
-/// A test VM whose `tools` and `packs` tables are installed over `set`.
+/// The run the offer tests share: `web` (`web/fetch`, `web/search`) and
+/// `user-input` (`user-input/ask`) declared; `gh` (`gh/issues.list`,
+/// `gh/search`) offered but undeclared; `subagents`, with no tool, able to
+/// serve; and `mcp` unable to, because "the mcp server is down". Every
+/// tool is bound under its wire name.
+#[track_caller]
+pub(crate) fn offer_set() -> ToolSet {
+ let pack = |name: &str| {
+ runvil_types::packs::PackId::parse(name).expect("a fixture Pack id is a valid Pack id")
+ };
+ let bind = |id: &str| crate::ToolBinding::from_info(&id.replace(['/', '.'], "_"), &tool_at(id));
+ ToolSet::new(
+ vec![pack("web"), pack("user-input")],
+ [
+ (pack("gh"), None),
+ (pack("mcp"), Some("the mcp server is down".to_owned())),
+ (pack("subagents"), None),
+ (pack("user-input"), None),
+ (pack("web"), None),
+ ]
+ .into_iter()
+ .collect(),
+ vec![
+ bind("gh/issues.list"),
+ bind("gh/search"),
+ bind("user-input/ask"),
+ bind("web/fetch"),
+ bind("web/search"),
+ ],
+ )
+}
+
+/// The offers `vm` recorded, each as `:`, the mode
+/// `static` or `dynamic`, in call order.
+#[track_caller]
+pub(crate) fn offers(vm: &SectionVm) -> Vec {
+ vm.tool_runtime()
+ .lock()
+ .expect("the runtime mutex is not poisoned")
+ .offers
+ .iter()
+ .map(|offer| {
+ let mode = match offer.mode {
+ crate::OfferMode::Static => "static",
+ crate::OfferMode::Dynamic => "dynamic",
+ };
+ match &offer.target {
+ crate::OfferTarget::Tool(id) => format!("{mode}:{id}"),
+ crate::OfferTarget::Pack(pack) => format!("{mode}:{pack}"),
+ }
+ })
+ .collect()
+}
+
+/// What `source` raises on `vm`, as text, failing the test when it runs
+/// clean.
+#[track_caller]
+pub(crate) fn raised(vm: &SectionVm, source: &str) -> String {
+ vm.lua()
+ .load(format!(
+ "local ok, err = pcall(function() {source} end)\n\
+ assert(not ok, 'the chunk must raise')\n\
+ return tostring(err)"
+ ))
+ .eval()
+ .unwrap_or_else(|error| panic!("{source}: {error}"))
+}
+
+/// A test VM whose `tools` table is installed over `set`.
#[track_caller]
pub(crate) fn lua_over(set: ToolSet) -> BuiltVm {
TestVm::new().tools(set).build()
@@ -119,13 +187,26 @@ pub(crate) fn lua_over(set: ToolSet) -> BuiltVm {
#[track_caller]
pub(crate) fn scoped(vm: &SectionVm) -> Vec {
let (set, runtime) = vm.tool_bag_handles();
- crate::current_tool_bindings(&set, &runtime)
+ crate::current_tool_bindings(&set, &runtime, vm.adhoc_tools())
.expect("the scope resolves")
.iter()
.map(|binding| binding.alias().to_owned())
.collect()
}
+/// The ids of the dynamic list a round on `vm` would store, in order.
+#[track_caller]
+pub(crate) fn dynamic(vm: &SectionVm) -> Vec {
+ let (set, runtime) = vm.tool_bag_handles();
+ let adhoc = vm.adhoc_tools();
+ let bound = crate::current_tool_bindings(&set, &runtime, adhoc).expect("the scope resolves");
+ crate::current_dynamic_tools(&set, &runtime, adhoc, &bound)
+ .expect("the dynamic list resolves")
+ .iter()
+ .map(ToString::to_string)
+ .collect()
+}
+
/// A section VM's setup as data. Unset, the VM shares an empty tool and
/// model set, reports nowhere under [`TEST_SECTION`], gets a fresh store,
/// empty `args` and `sys`, a frozen nil `argv`, and an empty `var`.
diff --git a/crates/runvil-internal/lua/src/tests/diagnostics.rs b/crates/runvil-internal/lua/src/tests/diagnostics.rs
index 12309bf5a..1291221d7 100644
--- a/crates/runvil-internal/lua/src/tests/diagnostics.rs
+++ b/crates/runvil-internal/lua/src/tests/diagnostics.rs
@@ -4,7 +4,7 @@
use super::*;
use crate::program::map_chunk_line_to_absolute;
-use crate::vm::LocalTools;
+use crate::vm::AdhocTools;
#[test]
fn lua_program_retains_source_and_round_trips_bytecode() {
@@ -62,38 +62,34 @@ fn runtime_assert_failure_reports_chunk_name_and_line() {
}
#[test]
-fn local_tools_schema_and_membership_reads_fail_closed_on_poison() {
- let local = LocalTools::default();
- let schema = runvil_model_client::detail::tool_schema_new(
- "grab".to_owned(),
- "Grab a value".to_owned(),
+fn adhoc_tools_list_and_lookup_reads_fail_closed_on_poison() {
+ let adhoc = AdhocTools::default();
+ let info = runvil_types::tools::ToolInfo::new(
+ runvil_types::tools::ToolId::parse("adhoc/grab").expect("a valid adhoc id"),
+ "Grab a value",
serde_json::json!({ "type": "object", "properties": {} }),
- )
- .expect("the schema builds");
- local
- .register(
- crate::alias::Alias::parse("grab".to_owned()).expect("a valid alias"),
- schema,
- )
+ );
+ adhoc
+ .register(crate::ToolBinding::from_info("grab", &info))
.expect("registration succeeds before the poison");
- let handle = local.entries_handle();
+ let handle = adhoc.entries_handle();
let poisoned = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
let _guard = handle.lock().expect("first lock is not poisoned");
- panic!("poison the local tools registry");
+ panic!("poison the adhoc tools registry");
}));
assert!(poisoned.is_err(), "the panic must poison the registry");
- let schemas = local
- .schemas()
- .expect_err("schema reads must fail on a poisoned registry");
- let contains = local
- .contains("anything")
- .expect_err("membership reads must fail on a poisoned registry");
- for error in [schemas, contains] {
+ let listed = adhoc
+ .bindings()
+ .expect_err("list reads must fail on a poisoned registry");
+ let looked_up = adhoc
+ .binding("adhoc/grab")
+ .expect_err("lookups must fail on a poisoned registry");
+ for error in [listed, looked_up] {
assert!(
error
.to_string()
- .contains("local tools registry was poisoned"),
+ .contains("adhoc tools registry was poisoned"),
"the concrete poison error must surface: {error}"
);
}
diff --git a/crates/runvil-internal/lua/src/tests/section_vm.rs b/crates/runvil-internal/lua/src/tests/section_vm.rs
index 21a8eb559..7c37af060 100644
--- a/crates/runvil-internal/lua/src/tests/section_vm.rs
+++ b/crates/runvil-internal/lua/src/tests/section_vm.rs
@@ -425,7 +425,8 @@ fn a_chunk_sees_the_tools_table_and_no_tool_global_ever_installs() {
Some("nil")
);
let (bindings, runtime) = vm.tool_bag_handles();
- let scope = current_tool_bindings(&bindings, &runtime).expect("tool scope must snapshot");
+ let scope = current_tool_bindings(&bindings, &runtime, vm.adhoc_tools())
+ .expect("tool scope must snapshot");
assert_eq!(
scope.iter().map(ToolBinding::alias).collect::>(),
["fixtures_search"],
@@ -460,7 +461,8 @@ fn functions_resolve_engine_globals_when_called_from_a_later_chunk() {
Some("fixtures/search")
);
let (bindings, runtime) = vm.tool_bag_handles();
- let scope = current_tool_bindings(&bindings, &runtime).expect("tool scope must snapshot");
+ let scope = current_tool_bindings(&bindings, &runtime, vm.adhoc_tools())
+ .expect("tool scope must snapshot");
assert_eq!(
scope.iter().map(ToolBinding::alias).collect::>(),
["fixtures_search"]
diff --git a/crates/runvil-internal/lua/src/tests/tool_scoping.rs b/crates/runvil-internal/lua/src/tests/tool_scoping.rs
index 420e29c4c..d20b3bb37 100644
--- a/crates/runvil-internal/lua/src/tests/tool_scoping.rs
+++ b/crates/runvil-internal/lua/src/tests/tool_scoping.rs
@@ -54,7 +54,8 @@ fn section_scope_keeps_each_tool_at_its_first_offer() {
let vm = TestVm::new().tools(bindings).build();
run_scalar(&vm, &prologue, &null_emitter(), "Section").expect("section offers must record");
let (bindings, runtime) = vm.tool_bag_handles();
- let scope = current_tool_bindings(&bindings, &runtime).expect("tool scope must snapshot");
+ let scope = current_tool_bindings(&bindings, &runtime, vm.adhoc_tools())
+ .expect("tool scope must snapshot");
assert_eq!(
scope.iter().map(ToolBinding::alias).collect::>(),
@@ -75,7 +76,8 @@ fn tools_offer_accepts_tool_objects_and_arrays() {
run_scalar(&vm, &prologue, &null_emitter(), "Section")
.expect("tools.offer must accept tool objects, ids, and arrays");
let (bindings, runtime) = vm.tool_bag_handles();
- let scope = current_tool_bindings(&bindings, &runtime).expect("tool scope must snapshot");
+ let scope = current_tool_bindings(&bindings, &runtime, vm.adhoc_tools())
+ .expect("tool scope must snapshot");
assert_eq!(
scope.iter().map(ToolBinding::alias).collect::>(),
@@ -97,7 +99,8 @@ fn empty_offer_is_a_no_op_and_failed_bulk_offer_is_atomic() {
run_scalar(&vm, &prologue, &null_emitter(), "Section")
.expect("caught failed offer must not poison recording");
let (bindings, runtime) = vm.tool_bag_handles();
- let scope = current_tool_bindings(&bindings, &runtime).expect("tool scope must snapshot");
+ let scope = current_tool_bindings(&bindings, &runtime, vm.adhoc_tools())
+ .expect("tool scope must snapshot");
assert_eq!(
scope.iter().map(ToolBinding::alias).collect::>(),
@@ -110,7 +113,7 @@ fn empty_offer_is_a_no_op_and_failed_bulk_offer_is_atomic() {
fn offer_rejects_a_second_argument_and_records_nothing() {
let bindings = fixture_set(&[("search", "search the web")]);
let prologue = program(
- "local extra = 'tools.offer takes one tool or a list of them, got extra string'; \
+ "local extra = 'tools.offer takes one tool or Pack, or an array of them, got extra string'; \
local ok, err = pcall(tools.offer, 'fixtures/search', 'a description'); \
if ok or not string.find(tostring(err), extra, 1, true) then \
error('a second argument to a single offer must fail loudly: ' .. tostring(err)) \
@@ -125,7 +128,8 @@ fn offer_rejects_a_second_argument_and_records_nothing() {
run_scalar(&vm, &prologue, &null_emitter(), "Section")
.expect("refused offers must not poison recording");
let (bindings, runtime) = vm.tool_bag_handles();
- let scope = current_tool_bindings(&bindings, &runtime).expect("tool scope must snapshot");
+ let scope = current_tool_bindings(&bindings, &runtime, vm.adhoc_tools())
+ .expect("tool scope must snapshot");
assert_eq!(
scope.iter().map(ToolBinding::alias).collect::>(),
@@ -150,7 +154,7 @@ fn an_unknown_id_fails_before_scope_closure() {
assert!(
error
.to_string()
- .contains("tools.offer: \"fixtures/missing\" is not a catalog tool in this run"),
+ .contains("tools.offer: \"fixtures/missing\" is not a tool in this run"),
"the error names the id: {error}"
);
vm.teardown();
@@ -189,7 +193,7 @@ fn offer_over_an_empty_offering_fails_in_a_chunk() {
assert!(
error
.to_string()
- .contains("tools.offer: \"web/search\" is not a catalog tool in this run"),
+ .contains("tools.offer: \"web/search\" is not a tool in this run"),
"the error must name the id: {error}"
);
}
@@ -205,9 +209,7 @@ fn offer_over_an_empty_offering_fails_in_a_prologue() {
)
.expect_err("an unoffered id must fail loudly");
assert!(
- error
- .to_string()
- .contains("is not a catalog tool in this run"),
+ error.to_string().contains("is not a tool in this run"),
"the error must report the missing tool: {error}"
);
vm.teardown();
@@ -217,7 +219,8 @@ fn offer_over_an_empty_offering_fails_in_a_prologue() {
fn a_section_vm_over_an_empty_offering_snapshots_to_an_empty_scope() {
let vm = TestVm::new().build();
let (bindings, runtime) = vm.tool_bag_handles();
- let scope = current_tool_bindings(&bindings, &runtime).expect("an empty scope must snapshot");
+ let scope = current_tool_bindings(&bindings, &runtime, vm.adhoc_tools())
+ .expect("an empty scope must snapshot");
assert!(scope.is_empty());
vm.teardown();
}
diff --git a/crates/runvil-internal/lua/src/tools.rs b/crates/runvil-internal/lua/src/tools.rs
index 9e1f77902..b02c15eab 100644
--- a/crates/runvil-internal/lua/src/tools.rs
+++ b/crates/runvil-internal/lua/src/tools.rs
@@ -1,50 +1,55 @@
-//! The `tools` namespace: scoping, invocation, and counts.
+//! The `tools` namespace: offering, adhoc tools, invocation, and counts.
//!
//! One Lua table holds every tool operation, mirroring the `models.*`
//! namespacing of model operations. The shared [`ToolSet`] holds every
//! catalog tool the run can offer, each bound under its wire name: its id
//! with `/` and `.` replaced by `_`, such as `web_fetch`. The model sees
-//! only wire names; Lua names a tool by its canonical id (`web/fetch`) or
-//! by its tool object, and never by a global. `required` and `extras` list
-//! the tool objects of the declared Packs and of every other Pack,
-//! `get` reads one by id, `offer` scopes tools into the section,
-//! `offer_local` registers a prompt-author Lua function as a tool, `call`
-//! dispatches a catalog or local tool (installed by the coroutine shim
-//! prelude, since dispatch suspends), and `calls` is the read-only
-//! dispatch counter surface, keyed by id for a catalog tool and by alias
-//! for a local one. Offering an id the run cannot offer is a
-//! hard error, and so is every offer once the section's first loop round
-//! rendered its tool list. The installation logic sits here, out of the
-//! VM driver; the VM only calls the installers in setup order.
+//! only wire names; Lua names a tool by its id (`web/fetch`) or by its
+//! tool object, and a Pack by its id (`web`) or its Pack object, never by
+//! a global. `adhoc` defines a prompt-author Lua function as a tool of the
+//! adhoc Pack, `get` reads one tool object by id, `packs` reads the Pack
+//! objects, `offer` and `offer_dynamic` remember tools and Packs for the
+//! section's rendered and dynamic lists, `call` dispatches a tool by id
+//! or object (installed by the coroutine shim prelude, since dispatch
+//! suspends), and `calls` is the read-only dispatch counter surface, keyed
+//! by id. Offering what the run cannot offer is a hard error, and so is
+//! every offer once the section's first loop round rendered its tool
+//! list. The installation logic sits here, out of the VM driver; the VM
+//! only calls the installers in setup order.
use std::sync::{Arc, Mutex};
-use mlua::{FromLuaMulti, Function, Lua, MultiValue, Table, Value, Variadic};
+use mlua::{Function, Lua, MultiValue, Table, Value};
use runvil_model_client::detail::tool_schema_new;
-use runvil_types::tools::ToolId;
+use runvil_types::tools::{ToolId, ToolInfo};
+use serde_json::{Value as Json, json};
use crate::alias::Alias;
use crate::error::{Error, Result};
use crate::handles::{ToolBinding, ToolSet};
+use crate::json::to_json;
use crate::messages::MessageList;
-use crate::scope::{ToolCallCounts, ToolRuntime};
-use crate::vm::LocalTools;
+use crate::packs::{ADHOC_PACK, install_pack_list, install_pack_objects};
+use crate::proxy::key_text;
+use crate::scope::{OfferMode, ToolCallCounts, ToolRuntime};
+use crate::vm::AdhocTools;
mod decode;
mod objects;
+mod offer;
mod userdata;
-pub(crate) use decode::tool_name;
+pub(crate) use decode::{model_tool_name, tool_name};
-use decode::{collect_offer_entries, local_params_schema};
+use decode::adhoc_params_schema;
pub(crate) use objects::tool_object;
-use objects::{install_tool_lists, install_tool_objects};
+use objects::{insert_tool_object, install_tool_get, install_tool_objects, remove_tool_object};
+use offer::{Offering, install_offer};
-/// The registry key of the VM's local-tool handler table:
-/// `tools.offer_local` writes each handler under its alias, and the
-/// scheduler's `Local` answer reads it back to hand the function to the
-/// shim.
-const LOCAL_HANDLERS_REGISTRY: &str = "runvil.tools.local_handlers";
+/// The registry key of the VM's adhoc-tool handler table: `tools.adhoc`
+/// writes each handler under its tool's wire name, and the scheduler's
+/// `Adhoc` answer reads it back to hand the function to the shim.
+const ADHOC_HANDLERS_REGISTRY: &str = "runvil.tools.adhoc_handlers";
/// The refusal of an offer function once the section's tool list is
/// rendered, after the calling function's name.
@@ -52,6 +57,10 @@ const TOOL_LIST_FIXED: &str = "the section's tool list is fixed at its first mod
make every offer before the first loop, or offer in another \
section";
+/// The prefix of a `tools.adhoc` JSON Schema `parameters` table that has no
+/// JSON form.
+const PARAMETERS_NOT_JSON: &str = "tools.adhoc: parameters schema cannot be encoded as JSON";
+
/// Refuses `call`, an offer function, once `list` holds the section's
/// rendered tool list.
pub(crate) fn refuse_after_render(call: &str, list: &MessageList) -> mlua::Result<()> {
@@ -61,35 +70,40 @@ pub(crate) fn refuse_after_render(call: &str, list: &MessageList) -> mlua::Resul
Ok(())
}
-/// Reads the handler `tools.offer_local` registered under `alias` from the
-/// VM's handler table.
+/// Reads the handler `tools.adhoc` registered under the wire name `name`
+/// from the VM's handler table.
///
/// # Errors
/// Returns an internal-invariant error when the table is absent or holds no
-/// function under `alias`: the scheduler answers `Local` only for an alias
-/// the VM reports as registered.
-pub(crate) fn local_handler(lua: &Lua, alias: &str) -> mlua::Result {
- let handlers: Option
= lua.named_registry_value(LOCAL_HANDLERS_REGISTRY)?;
+/// function under `name`: the scheduler answers `Adhoc` only for a tool
+/// the VM reports as defined.
+pub(crate) fn adhoc_handler(lua: &Lua, name: &str) -> mlua::Result {
+ let handlers: Option
= lua.named_registry_value(ADHOC_HANDLERS_REGISTRY)?;
let handler = match handlers {
- Some(handlers) => handlers.raw_get::(alias)?,
+ Some(handlers) => handlers.raw_get::(name)?,
None => Value::Nil,
};
match handler {
Value::Function(handler) => Ok(handler),
_ => Err(mlua::Error::external(Error::Internal(
- "a local tool answer names a registered handler".into(),
+ "an adhoc tool answer names a registered handler".into(),
))),
}
}
/// Installs the read-only `tools.calls` counter table over `counts`;
-/// `offered`, the ids of every tool the run can offer, feeds the
-/// unknown-key diagnostic.
+/// `offered`, the ids of every tool the run can offer, and `adhoc`, the
+/// VM's adhoc tools, feed the unknown-key diagnostic.
///
/// # Errors
/// Returns [`Error::LuaRuntime`] if the Lua table or callbacks cannot be created or
/// installed.
-fn install_lua_tool_calls(lua: &Lua, counts: &ToolCallCounts, offered: Vec) -> Result<()> {
+fn install_lua_tool_calls(
+ lua: &Lua,
+ counts: &ToolCallCounts,
+ offered: Vec,
+ adhoc: AdhocTools,
+) -> Result<()> {
let globals = lua.globals();
let tools: Table = globals.raw_get("tools").map_err(Error::lua)?;
@@ -101,23 +115,28 @@ fn install_lua_tool_calls(lua: &Lua, counts: &ToolCallCounts, offered: Vec Result {
- let counts = ToolCallCounts::new(bindings.iter().map(|b| b.id().to_string()));
+ let counts = ToolCallCounts::new(ids.iter().map(ToString::to_string));
let offered: Vec = bound_tools
.offered()
.iter()
.map(|binding| binding.id().to_string())
.collect();
- install_lua_tool_calls(lua, &counts, offered)?;
+ install_lua_tool_calls(lua, &counts, offered, adhoc.clone())?;
Ok(counts)
}
-/// Resolves each of `call`'s entries to its offered binding's wire name,
-/// checking every entry before the caller records any: an entry must parse
-/// as a tool id, so a wire name, a malformed id, or a local alias is
-/// refused as an id the run does not offer.
-fn resolve_entries(call: &str, set: &ToolSet, entries: Vec) -> mlua::Result> {
- entries
- .into_iter()
- .map(|name| {
- let binding = match ToolId::parse(&name) {
- Ok(_) => set.offered_binding(&name),
- Err(_) => None,
- };
- match binding {
- Some(binding) => Ok(binding.alias().to_owned()),
- None => Err(mlua::Error::external(format!(
- "{call}: {name:?} is not a catalog tool in this run"
- ))),
- }
- })
- .collect()
-}
-
-/// Installs the tool scoping and local-tool APIs into one section VM (H1
-/// included: there is one install path for every section).
+/// Installs the tool and Pack APIs into one section VM (H1 included: there
+/// is one install path for every section): the tool objects, the Pack
+/// objects, `tools.packs`, both offer verbs, `tools.adhoc`, and
+/// `tools.get`.
///
/// The coroutine shim prelude installs the suspending `tools.call` on this
/// table as a Lua function, because yield cannot cross the Rust callback
-/// boundary. Both offer functions refuse once `list`, the section's
+/// boundary. Both offer verbs refuse once `list`, the section's
/// conversation, holds a rendered tool list.
///
/// # Errors
@@ -201,96 +201,176 @@ pub(crate) fn install_tools(
globals: &Table,
set: &Arc,
runtime: &Arc>,
- local_tools: &LocalTools,
+ adhoc_tools: &AdhocTools,
list: &MessageList,
) -> Result<()> {
let tools = lua.create_table().map_err(Error::lua)?;
install_tool_objects(lua, set)?;
- install_offer(lua, &tools, set, runtime, list)?;
- install_tool_lists(lua, &tools, set)?;
- install_offer_local(lua, &tools, local_tools, list)?;
+ let names = install_pack_objects(lua, set, adhoc_tools)?;
+ install_pack_list(lua, &tools, names)?;
+ let offering = Offering {
+ set: Arc::clone(set),
+ runtime: Arc::clone(runtime),
+ adhoc: adhoc_tools.clone(),
+ list: list.clone(),
+ };
+ install_offer(lua, &tools, "offer", OfferMode::Static, &offering)?;
+ install_offer(lua, &tools, "offer_dynamic", OfferMode::Dynamic, &offering)?;
+ install_adhoc(lua, &tools, adhoc_tools)?;
+ install_tool_get(lua, &tools)?;
globals.raw_set("tools", tools).map_err(Error::lua)
}
-/// Installs `tools.offer(tool)` and its array form: each tool enters the
-/// section's scope once, under its wire name, in first-offer order.
-fn install_offer(
- lua: &Lua,
- tools: &Table,
- set: &Arc,
- runtime: &Arc>,
- list: &MessageList,
-) -> Result<()> {
- let frozen = Arc::clone(set);
- let state = Arc::clone(runtime);
- let list = list.clone();
- let offer = lua
- .create_function(move |_, args: Variadic| {
- refuse_after_render("tools.offer", &list)?;
- let entries = collect_offer_entries("tools.offer", args)?;
- let resolved = resolve_entries("tools.offer", &frozen, entries)?;
- let mut state = state
- .lock()
- .map_err(|_| mlua::Error::external("tool declaration runtime was poisoned"))?;
- for name in resolved {
- if !state.added.iter().any(|existing| existing == &name) {
- state.added.push(name);
- }
- }
- Ok(())
- })
- .map_err(Error::lua)?;
- tools.set("offer", offer).map_err(Error::lua)
-}
-
-/// Installs `tools.offer_local(alias, description, params, handler)` over
-/// a fresh handler table: the alias and schema register on `local_tools`
-/// for membership and advertising, and the handler is written under the
-/// alias for the scheduler's `Local` answer to read back. An alias may
-/// equal an offered tool's wire name; the local tool wins in scope. The
-/// arguments convert after the rendered-list check, so that refusal comes
-/// first.
-fn install_offer_local(
- lua: &Lua,
- tools: &Table,
- local_tools: &LocalTools,
- list: &MessageList,
-) -> Result<()> {
+/// Installs `tools.adhoc(attrs, f)` over a fresh handler table: `f` is
+/// written under the tool's wire name for the scheduler's `Adhoc` answer
+/// to read back, the tool object is stored in the tool-object registry,
+/// the tool registers on `adhoc_tools`, and the tool object is returned.
+/// A definition is all or nothing: the tool registers last, and a failed
+/// registration clears the handler and the object, so a definition that
+/// fails at any point leaves no tool defined and the name free to define
+/// again. Defining offers nothing, and works before and after the section
+/// renders.
+fn install_adhoc(lua: &Lua, tools: &Table, adhoc_tools: &AdhocTools) -> Result<()> {
lua.set_named_registry_value(
- LOCAL_HANDLERS_REGISTRY,
+ ADHOC_HANDLERS_REGISTRY,
lua.create_table().map_err(Error::lua)?,
)
.map_err(Error::lua)?;
- let local = local_tools.clone();
- let list = list.clone();
- let offer_local = lua
+ let adhoc = adhoc_tools.clone();
+ let define = lua
.create_function(move |lua, args: MultiValue| {
- refuse_after_render("tools.offer_local", &list)?;
- let (alias, description, params, handler) =
- <(String, String, Table, Function)>::from_lua_args(args, 1, None, lua)?;
- let alias = Alias::parse(alias).map_err(mlua::Error::external)?;
- if local
- .contains(alias.as_str())
- .map_err(mlua::Error::external)?
- {
+ let mut args = args.into_iter();
+ let attrs = match args.next().unwrap_or(Value::Nil) {
+ Value::Table(attrs) => attrs,
+ other => {
+ return Err(mlua::Error::external(format!(
+ "tools.adhoc takes an attrs table first, got {}",
+ other.type_name()
+ )));
+ }
+ };
+ let handler = match args.next().unwrap_or(Value::Nil) {
+ Value::Function(handler) => handler,
+ other => {
+ return Err(mlua::Error::external(format!(
+ "tools.adhoc takes the tool's function second, got {}",
+ other.type_name()
+ )));
+ }
+ };
+ if let Some(extra) = args.next() {
return Err(mlua::Error::external(format!(
- "tools.offer_local alias {:?} is already registered",
- alias.as_str()
+ "tools.adhoc takes two arguments, got extra {}",
+ extra.type_name()
)));
}
- let parameters = local_params_schema(¶ms)?;
- let schema = tool_schema_new(alias.as_str(), description, parameters)
- .map_err(mlua::Error::external)?;
- let handlers: Table = lua.named_registry_value(LOCAL_HANDLERS_REGISTRY)?;
- handlers.raw_set(alias.as_str(), handler)?;
- local
- .register(alias, schema)
- .map_err(mlua::Error::external)?;
- Ok(())
+ let (name, info) = adhoc_info(lua, &attrs, &adhoc)?;
+ let binding = ToolBinding::from_info(&name, &info);
+ let handlers: Table = lua.named_registry_value(ADHOC_HANDLERS_REGISTRY)?;
+ handlers.raw_set(name.as_str(), handler)?;
+ let object = insert_tool_object(lua, &binding)?;
+ let id = binding.id().to_string();
+ if let Err(error) = adhoc.register(binding) {
+ handlers.raw_set(name, Value::Nil)?;
+ remove_tool_object(lua, &id)?;
+ return Err(mlua::Error::external(error));
+ }
+ Ok(object)
})
.map_err(Error::lua)?;
- tools.set("offer_local", offer_local).map_err(Error::lua)
+ tools.set("adhoc", define).map_err(Error::lua)
+}
+
+/// Reads `tools.adhoc`'s attrs as the tool's wire name and info, checking
+/// the keys, the name, the description, the parameters, and the schema,
+/// and that neither the name nor the id is taken.
+fn adhoc_info(lua: &Lua, attrs: &Table, adhoc: &AdhocTools) -> mlua::Result<(String, ToolInfo)> {
+ let mut unknown: Vec = Vec::new();
+ for pair in attrs.pairs::() {
+ let (key, _) = pair?;
+ let known = matches!(&key, Value::String(text)
+ if text == "name" || text == "description" || text == "parameters");
+ if !known {
+ unknown.push(key_text(&key));
+ }
+ }
+ unknown.sort();
+ if let Some(key) = unknown.first() {
+ return Err(mlua::Error::external(format!(
+ "tools.adhoc: unknown key {key:?}; accepted keys are name, description, parameters"
+ )));
+ }
+ let name = attr_text(attrs, "name")?;
+ let name = String::from(Alias::parse(name.clone()).map_err(|_| {
+ mlua::Error::external(format!(
+ "tools.adhoc: invalid name {name:?}: expected [A-Za-z][A-Za-z0-9_-]{{0,63}}"
+ ))
+ })?);
+ let description = attr_text(attrs, "description")?;
+ let id = format!("{ADHOC_PACK}/{}", name.to_ascii_lowercase());
+ if adhoc
+ .binding(&name)
+ .map_err(mlua::Error::external)?
+ .is_some()
+ {
+ return Err(mlua::Error::external(format!(
+ "tools.adhoc name {name:?} is already registered"
+ )));
+ }
+ if let Some(holder) = adhoc.binding(&id).map_err(mlua::Error::external)? {
+ return Err(mlua::Error::external(format!(
+ "tools.adhoc name {name:?} has the id {id}, which {:?} already holds",
+ holder.alias()
+ )));
+ }
+ let parameters = match attrs.raw_get::("parameters")? {
+ Value::Nil => json!({ "type": "object", "properties": {}, "required": [] }),
+ Value::Table(parameters) => parameters_schema(lua, ¶meters)?,
+ other => {
+ return Err(mlua::Error::external(format!(
+ "tools.adhoc: parameters must be a table, got {}",
+ other.type_name()
+ )));
+ }
+ };
+ tool_schema_new(name.clone(), description.clone(), parameters.clone())
+ .map_err(|error| mlua::Error::external(format!("tools.adhoc: {error}")))?;
+ let id = ToolId::parse(&id).map_err(|error| {
+ mlua::Error::external(Error::Internal(
+ format!("an adhoc tool's id is a tool id: {error}").into(),
+ ))
+ })?;
+ Ok((name, ToolInfo::new(id, description, parameters)))
+}
+
+/// Reads the required string attr `key`.
+fn attr_text(attrs: &Table, key: &str) -> mlua::Result {
+ match attrs.raw_get::(key)? {
+ Value::String(text) => Ok(text.to_string_lossy()),
+ Value::Nil => Err(mlua::Error::external(format!(
+ "tools.adhoc: {key:?} is required"
+ ))),
+ other => Err(mlua::Error::external(format!(
+ "tools.adhoc: {key:?} must be a string, got {}",
+ other.type_name()
+ ))),
+ }
+}
+
+/// The schema a `parameters` table declares: a JSON Schema object when
+/// its `type` is `"object"`, as `json.encode` converts it, else the short
+/// form, one type name or `{type, description}` per parameter.
+fn parameters_schema(lua: &Lua, parameters: &Table) -> mlua::Result {
+ match parameters.raw_get::("type")? {
+ Value::String(kind) if kind == "object" => to_json(
+ lua,
+ PARAMETERS_NOT_JSON,
+ false,
+ &Value::Table(parameters.clone()),
+ ),
+ _ => adhoc_params_schema(parameters),
+ }
}
#[cfg(test)]
diff --git a/crates/runvil-internal/lua/src/tools/decode.rs b/crates/runvil-internal/lua/src/tools/decode.rs
index a5ae2a8d4..764b6857e 100644
--- a/crates/runvil-internal/lua/src/tools/decode.rs
+++ b/crates/runvil-internal/lua/src/tools/decode.rs
@@ -1,90 +1,75 @@
//! Shared value decoding for the `tools.*` Engine functions.
//!
-//! The id-or-tool-object polymorphism lives here once: `tools.offer` and
-//! the `tools.call` protocol parse both accept a bare string or a tool
-//! object and resolve each to the name it stands for, a tool object
-//! standing for its canonical id. The
-//! `tools.offer_local` params-table-to-JSON-Schema conversion sits beside
-//! it as the namespace's other argument decode.
+//! The id-or-tool-object polymorphism of `tools.call` lives here once: a
+//! string holding a `/` is a tool id and a tool object stands for its id.
+//! The short-form `parameters` conversion of `tools.adhoc` sits beside it
+//! as the namespace's other argument decode.
-use mlua::{Value, Variadic};
+use mlua::Value;
use serde_json::{Value as Json, json};
use super::userdata::LuaToolHandle;
-/// Resolves one string or tool object to the name it stands for.
+/// Resolves the tool a script's `tools.call` names to its id.
///
-/// This is the single decode behind the namespace's argument polymorphism:
-/// a string is the name verbatim (a tool id, or for `tools.call` a local
-/// alias), a tool object contributes its canonical id, and anything else
-/// is an argument error naming the accepted forms.
+/// A string holding a `/` is the id verbatim, a tool object contributes
+/// its id, and anything else is an argument error naming the accepted
+/// forms.
///
/// # Errors
-/// Returns an `mlua` external error when the value is neither a string nor
-/// a tool object.
+/// Returns an `mlua` external error when the value is neither a string
+/// holding a `/` nor a tool object.
pub(crate) fn tool_name(value: &Value) -> mlua::Result {
- let rejected = || {
- mlua::Error::external(format!(
- "tools.call takes a tool id, a local alias, or a tool object, got {}",
- value.type_name()
- ))
- };
match value {
- Value::String(s) => Ok(s.to_string_lossy()),
- // A userdata that is not a tool object (a model handle) takes the
- // same rejection as any other wrong type.
- Value::UserData(ud) => ud
- .borrow::()
- .map(|handle| handle.id().to_string())
- .map_err(|_| rejected()),
- _ => Err(rejected()),
+ Value::String(text) => {
+ let name = text.to_string_lossy();
+ if name.contains('/') {
+ Ok(name)
+ } else {
+ Err(mlua::Error::external(format!(
+ "tools.call: {name:?} is not a tool id"
+ )))
+ }
+ }
+ other => object_id(other).ok_or_else(|| {
+ mlua::Error::external(format!(
+ "tools.call takes a tool id or a tool object, got {}",
+ other.type_name()
+ ))
+ }),
}
}
-/// Reads one element of `call`'s arguments as a name: a string or a tool
-/// object.
-fn entry_name(call: &str, value: &Value) -> mlua::Result {
- tool_name(value).map_err(|_| {
- mlua::Error::external(format!(
- "{call} takes tool ids, tool objects, or arrays of them, got {}",
- value.type_name()
- ))
- })
-}
-
-/// Flattens the arguments of `call` (`tools.offer`) into the names they
-/// stand for, naming `call` in every argument-shape error.
+/// Resolves the tool a model-issued call names: the wire name the model
+/// sent, verbatim.
///
-/// `tools.offer(tool)` takes one tool id or tool object. A table is the
-/// array form, `tools.offer({"web/search", "web/fetch"})` or
-/// `tools.offer(tools.extras())`, which covers bulk. Any second argument is
-/// refused.
-pub(super) fn collect_offer_entries(
- call: &str,
- args: Variadic,
-) -> mlua::Result> {
- let mut args = args.into_iter();
- let Some(target) = args.next() else {
- return Ok(Vec::new());
- };
- if let Some(extra) = args.next() {
- return Err(mlua::Error::external(format!(
- "{call} takes one tool or a list of them, got extra {}",
- extra.type_name()
- )));
+/// # Errors
+/// Returns an `mlua` external error when the value is not a string.
+pub(crate) fn model_tool_name(value: &Value) -> mlua::Result {
+ match value {
+ Value::String(text) => Ok(text.to_string_lossy()),
+ other => Err(mlua::Error::external(format!(
+ "a model-issued tool call names a tool by its wire name, got {}",
+ other.type_name()
+ ))),
}
- match target {
- Value::Table(table) => table
- .sequence_values::()
- .map(|item| entry_name(call, &item?))
- .collect(),
- single => Ok(vec![entry_name(call, &single)?]),
+}
+
+/// The id of the tool object `value` is, or `None` for any other value,
+/// a userdata that is not a tool object included.
+pub(super) fn object_id(value: &Value) -> Option {
+ match value {
+ Value::UserData(object) => object
+ .borrow::()
+ .ok()
+ .map(|handle| handle.id().to_string()),
+ _ => None,
}
}
-/// Builds the JSON Schema `parameters` object from a `tools.offer_local` params
-/// table. Each value is a bare type string or a `{type, description}` array;
-/// every declared parameter is required.
+/// Builds the JSON Schema `parameters` object from the short form of a
+/// `tools.adhoc` `parameters` table. Each value is a bare type string or a
+/// `{type, description}` array; every declared parameter is required.
///
/// The `required` list is the only Rust-side `table.pairs` walk in this crate
/// that builds an ordered array without sorting it, so it sorts its names
@@ -93,7 +78,7 @@ pub(super) fn collect_offer_entries(
/// walk's order is unspecified, so a schema left in it would read differently
/// in two VMs; `properties` needs no sort because it is a `serde_json::Map`,
/// a `BTreeMap` with no `preserve_order` in the graph.
-pub(super) fn local_params_schema(params: &mlua::Table) -> mlua::Result {
+pub(super) fn adhoc_params_schema(params: &mlua::Table) -> mlua::Result {
let mut properties = serde_json::Map::new();
let mut required = Vec::new();
for pair in params.pairs::() {
@@ -103,13 +88,13 @@ pub(super) fn local_params_schema(params: &mlua::Table) -> mlua::Result {
Value::Table(t) => (t.get::(1)?, t.get::>(2)?),
_ => {
return Err(mlua::Error::external(format!(
- "tools.offer_local param {name:?} must be a type string or a {{type, description}} array"
+ "tools.adhoc: param {name:?} must be a type string or a {{type, description}} array"
)));
}
};
if !matches!(ty.as_str(), "string" | "integer" | "number" | "boolean") {
return Err(mlua::Error::external(format!(
- "tools.offer_local param {name:?} has unsupported type {ty:?}: \
+ "tools.adhoc: param {name:?} has unsupported type {ty:?}: \
expected \"string\", \"integer\", \"number\", or \"boolean\""
)));
}
diff --git a/crates/runvil-internal/lua/src/tools/objects.rs b/crates/runvil-internal/lua/src/tools/objects.rs
index 721581b3e..a5a7e83b2 100644
--- a/crates/runvil-internal/lua/src/tools/objects.rs
+++ b/crates/runvil-internal/lua/src/tools/objects.rs
@@ -1,24 +1,23 @@
-//! Tool objects: one frozen [`LuaToolHandle`] per offered tool, built once
-//! per VM, and `tools.required`, `tools.extras`, and `tools.get` over them.
+//! Tool objects: one frozen [`LuaToolHandle`] per offered catalog tool,
+//! built once per VM, one per adhoc tool, added as `tools.adhoc` defines
+//! it, and `tools.get` over them.
//!
-//! Every list hands out the same userdata for a tool, so a tool read
-//! through any of them compares `==` to the same tool read through
-//! another, while each list call builds a fresh array.
-
-use std::sync::Arc;
+//! Every read hands out the same userdata for a tool, so a tool read
+//! through `tools.get` compares `==` to the same tool read through a
+//! Pack's `tools`, while each `tools` read builds a fresh array.
use mlua::{AnyUserData, Lua, Table, Value};
use super::userdata::LuaToolHandle;
use crate::error::{Error, Result};
-use crate::handles::ToolSet;
+use crate::handles::{ToolBinding, ToolSet};
-/// The registry key of the VM's tool-object table: one object per offered
-/// tool, keyed by id, built when `install_tools` runs.
-const TOOL_OBJECTS_REGISTRY: &str = "runvil.tools.objects";
+/// The registry key of the VM's tool-object table: one object per tool,
+/// keyed by id.
+pub(super) const TOOL_OBJECTS_REGISTRY: &str = "runvil.tools.objects";
-/// The VM's tool object for the catalog id `id`, or `None` when the run
-/// cannot offer that tool.
+/// The VM's tool object for the id `id`, or `None` when the run cannot
+/// offer that tool and no adhoc tool holds that id.
///
/// # Errors
/// Returns an `mlua` error when the registry cannot be read.
@@ -52,32 +51,32 @@ pub(super) fn install_tool_objects(lua: &Lua, set: &ToolSet) -> Result<()> {
.map_err(Error::lua)
}
-/// Installs `tools.required()` and `tools.extras()`, the offered tools
-/// whose Pack the frontmatter declares and every other one, and
-/// `tools.get(id)`.
+/// Adds the tool object of the adhoc tool `binding` binds and returns it.
///
/// # Errors
-/// Returns [`Error::Lua`] if a function cannot be created or installed.
-pub(super) fn install_tool_lists(lua: &Lua, tools: &Table, set: &Arc) -> Result<()> {
- for (name, required) in [("required", true), ("extras", false)] {
- let set = Arc::clone(set);
- let list = lua
- .create_function(move |lua, ()| {
- let objects = lua.create_table()?;
- for binding in set
- .offered()
- .iter()
- .filter(|binding| set.declared().contains(&binding.id().pack()) == required)
- {
- if let Some(object) = tool_object(lua, &binding.id().to_string())? {
- objects.raw_push(object)?;
- }
- }
- Ok(objects)
- })
- .map_err(Error::lua)?;
- tools.set(name, list).map_err(Error::lua)?;
- }
+/// Returns an `mlua` error when the object cannot be created or stored.
+pub(super) fn insert_tool_object(lua: &Lua, binding: &ToolBinding) -> mlua::Result {
+ let objects: Table = lua.named_registry_value(TOOL_OBJECTS_REGISTRY)?;
+ let object = lua.create_userdata(LuaToolHandle::from_binding(binding))?;
+ objects.raw_set(binding.id().to_string(), object.clone())?;
+ Ok(object)
+}
+
+/// Clears the tool object stored under the id `id`.
+///
+/// # Errors
+/// Returns an `mlua` error when the tool-object table cannot be read or
+/// written.
+pub(super) fn remove_tool_object(lua: &Lua, id: &str) -> mlua::Result<()> {
+ let objects: Table = lua.named_registry_value(TOOL_OBJECTS_REGISTRY)?;
+ objects.raw_set(id, Value::Nil)
+}
+
+/// Installs `tools.get(id)`.
+///
+/// # Errors
+/// Returns [`Error::Lua`] if the function cannot be created or installed.
+pub(super) fn install_tool_get(lua: &Lua, tools: &Table) -> Result<()> {
let get = lua
.create_function(|lua, id: Value| match id {
Value::String(id) => tool_object(lua, &id.to_str()?),
diff --git a/crates/runvil-internal/lua/src/tools/offer.rs b/crates/runvil-internal/lua/src/tools/offer.rs
new file mode 100644
index 000000000..6db9f4b2d
--- /dev/null
+++ b/crates/runvil-internal/lua/src/tools/offer.rs
@@ -0,0 +1,239 @@
+//! The offer verbs, `tools.offer` and `tools.offer_dynamic`: one
+//! installer, parameterized by name and mode, and its decode.
+//!
+//! A verb takes one argument: a string with a `/`, a tool id; a string
+//! without one, a Pack id, since Pack ids are one segment and tool ids
+//! two or more; a tool object; a Pack object; or an array mixing them.
+//! An array is its `#t` entries, read through `__index`, with no gap, no
+//! nested table, and no raw key outside `1..#t`. The rendered-list
+//! refusal comes first, and every entry is checked before any is
+//! recorded.
+
+use std::sync::{Arc, Mutex};
+
+use mlua::{Lua, Table, Value, Variadic};
+use runvil_types::packs::PackId;
+use runvil_types::tools::ToolId;
+
+use super::refuse_after_render;
+use super::userdata::LuaToolHandle;
+use crate::error::{Error, Result};
+use crate::handles::ToolSet;
+use crate::messages::MessageList;
+use crate::packs::{LuaPackHandle, is_adhoc, pack_object};
+use crate::proxy::key_text;
+use crate::scope::{OfferMode, OfferTarget, ToolRuntime};
+use crate::vm::AdhocTools;
+use crate::walk_budget::HELD_KEY_LIMIT;
+
+/// What an offer verb checks its entries against and records into: the
+/// run's tool set, the section's offers, the VM's adhoc tools, and the
+/// section's conversation, whose rendered list fixes the offers.
+#[derive(Clone)]
+pub(super) struct Offering {
+ pub(super) set: Arc,
+ pub(super) runtime: Arc>,
+ pub(super) adhoc: AdhocTools,
+ pub(super) list: MessageList,
+}
+
+/// Installs the offer verb `tools.` on `tools`, recording under
+/// `mode`.
+///
+/// # Errors
+/// Returns [`Error::LuaRuntime`] if the function cannot be created or
+/// installed.
+pub(super) fn install_offer(
+ lua: &Lua,
+ tools: &Table,
+ key: &'static str,
+ mode: OfferMode,
+ offering: &Offering,
+) -> Result<()> {
+ let verb = format!("tools.{key}");
+ let offering = offering.clone();
+ let offer = lua
+ .create_function(move |lua, args: Variadic| {
+ refuse_after_render(&verb, &offering.list)?;
+ let targets = offering.targets(lua, &verb, args)?;
+ let mut runtime = offering
+ .runtime
+ .lock()
+ .map_err(|_| mlua::Error::external("tool declaration runtime was poisoned"))?;
+ for target in targets {
+ match target {
+ OfferTarget::Tool(id) => runtime.add_tool(id, mode),
+ OfferTarget::Pack(pack) => runtime.add_pack(pack, mode),
+ }
+ }
+ Ok(())
+ })
+ .map_err(Error::lua)?;
+ tools.set(key, offer).map_err(Error::lua)
+}
+
+impl Offering {
+ /// Reads `verb`'s arguments as the targets they name, checking every
+ /// entry before returning any. No argument names nothing.
+ fn targets(
+ &self,
+ lua: &Lua,
+ verb: &str,
+ args: Variadic,
+ ) -> mlua::Result> {
+ let mut args = args.into_iter();
+ let Some(target) = args.next() else {
+ return Ok(Vec::new());
+ };
+ if let Some(extra) = args.next() {
+ return Err(mlua::Error::external(format!(
+ "{verb} takes one tool or Pack, or an array of them, got extra {}",
+ extra.type_name()
+ )));
+ }
+ match target {
+ Value::Table(table) => array(verb, &table)?
+ .iter()
+ .enumerate()
+ .map(|(index, entry)| self.target(lua, verb, entry, Some(index + 1)))
+ .collect(),
+ single => Ok(vec![self.target(lua, verb, &single, None)?]),
+ }
+ }
+
+ /// Reads one entry, at `index` of an array or alone, as the tool or
+ /// Pack it names. A tool object under the `adhoc` Pack must be a
+ /// defined adhoc tool, since only those have a binding to render.
+ fn target(
+ &self,
+ lua: &Lua,
+ verb: &str,
+ entry: &Value,
+ index: Option,
+ ) -> mlua::Result {
+ match entry {
+ Value::String(text) => self.named(lua, verb, &text.to_string_lossy()),
+ Value::UserData(object) => {
+ if let Ok(tool) = object.borrow::() {
+ let id = tool.id();
+ if is_adhoc(&id.pack()) {
+ return self.named(lua, verb, &id.to_string());
+ }
+ return Ok(OfferTarget::Tool(id.clone()));
+ }
+ if let Ok(pack) = object.borrow::() {
+ return Ok(OfferTarget::Pack(pack.name().clone()));
+ }
+ Err(wrong_type(verb, entry, index))
+ }
+ other => Err(wrong_type(verb, other, index)),
+ }
+ }
+
+ /// Reads a string entry: with a `/`, the id of a tool in the offering
+ /// or a defined adhoc tool; without one, the id of a Pack with an
+ /// object.
+ fn named(&self, lua: &Lua, verb: &str, name: &str) -> mlua::Result {
+ if name.contains('/') {
+ let known = match ToolId::parse(name) {
+ Ok(id) if is_adhoc(&id.pack()) => self
+ .adhoc
+ .binding(name)
+ .map_err(mlua::Error::external)?
+ .is_some()
+ .then_some(id),
+ Ok(id) => self.set.offered_binding(name).is_some().then_some(id),
+ Err(_) => None,
+ };
+ return known.map(OfferTarget::Tool).ok_or_else(|| {
+ mlua::Error::external(format!("{verb}: {name:?} is not a tool in this run"))
+ });
+ }
+ if let Ok(pack) = PackId::parse(name) {
+ if let Some(Some(reason)) = self.set.roster().get(&pack) {
+ return Err(mlua::Error::external(format!(
+ "{verb}: the {pack} Pack is unavailable in this run: {reason}"
+ )));
+ }
+ if pack_object(lua, name)?.is_some() {
+ return Ok(OfferTarget::Pack(pack));
+ }
+ }
+ let hint = match self.wire_named(name)? {
+ Some(id) => format!(" (did you mean '{id}'?)"),
+ None => String::new(),
+ };
+ Err(mlua::Error::external(format!(
+ "{verb}: no Pack named {name:?} in this run; declare it under uses: to require \
+ it, or offer it only when tools.packs.get({name:?}) returns it{hint}"
+ )))
+ }
+
+ /// The id of the tool in the offering, or else the defined adhoc tool,
+ /// whose wire name is `name`.
+ fn wire_named(&self, name: &str) -> mlua::Result> {
+ if let Some(binding) = self.set.wire_binding(name) {
+ return Ok(Some(binding.id().clone()));
+ }
+ Ok(self
+ .adhoc
+ .binding(name)
+ .map_err(mlua::Error::external)?
+ .map(|binding| binding.id().clone()))
+ }
+}
+
+/// The entries of the array `table`: `#t` of them, honoring `__len`, each
+/// read through `__index`. A `#t` above [`HELD_KEY_LIMIT`] is refused
+/// before any entry is read, since each entry holds a Lua reference until
+/// the offer is recorded. A nil or a table in that range, or a raw key
+/// outside it, is refused.
+fn array(verb: &str, table: &Table) -> mlua::Result> {
+ let len = table.len()?;
+ let count = usize::try_from(len).unwrap_or(if len > 0 { usize::MAX } else { 0 });
+ if count > HELD_KEY_LIMIT {
+ return Err(mlua::Error::external(format!(
+ "{verb} takes an array of at most {HELD_KEY_LIMIT} entries, got {len}"
+ )));
+ }
+ let mut entries = Vec::with_capacity(count);
+ for index in 1..=count {
+ let entry: Value = table.get(index)?;
+ if matches!(entry, Value::Nil | Value::Table(_)) {
+ return Err(wrong_type(verb, &entry, Some(index)));
+ }
+ entries.push(entry);
+ }
+ for pair in table.pairs::() {
+ let (key, _) = pair?;
+ let inside = match key {
+ Value::Integer(index) => {
+ usize::try_from(index).is_ok_and(|index| (1..=count).contains(&index))
+ }
+ _ => false,
+ };
+ if !inside {
+ return Err(mlua::Error::external(format!(
+ "{verb} takes an array, got a table with the key {}",
+ key_text(&key)
+ )));
+ }
+ }
+ Ok(entries)
+}
+
+/// The refusal of `entry`, at `index` of an array or alone, as a value
+/// that names no tool or Pack.
+fn wrong_type(verb: &str, entry: &Value, index: Option) -> mlua::Error {
+ let kind = entry.type_name();
+ mlua::Error::external(match index {
+ Some(index) => format!(
+ "{verb} takes tool ids, Pack ids, tool objects, or Pack objects in an array, \
+ got {kind} at index {index}"
+ ),
+ None => format!(
+ "{verb} takes tool ids, Pack ids, tool objects, Pack objects, or an array of \
+ them, got {kind}"
+ ),
+ })
+}
diff --git a/crates/runvil-internal/lua/src/tools/tests-adhoc.rs b/crates/runvil-internal/lua/src/tools/tests-adhoc.rs
new file mode 100644
index 000000000..9ee2a9cbd
--- /dev/null
+++ b/crates/runvil-internal/lua/src/tools/tests-adhoc.rs
@@ -0,0 +1,322 @@
+//! Tests for `tools.adhoc`: the tool object it returns, the id and wire
+//! name it gives, the schema it builds from `parameters`, its refusals,
+//! a definition that fails partway, the adhoc Pack, and the counts an
+//! adhoc tool keys.
+
+use mlua::{LuaSerdeExt, Table, Value};
+use serde_json::{Value as Json, json};
+
+use super::super::objects::TOOL_OBJECTS_REGISTRY;
+use super::parameters::search_set;
+use crate::Argv;
+use crate::test_vm::{TestVm, lua_over, offer_set, raised, scoped};
+
+/// The `grab` definition of the listing, held in a local.
+const GRAB: &str = "local grab = tools.adhoc({\n\
+ name = 'grab',\n\
+ description = 'Grab a value',\n\
+ parameters = { value = 'string' },\n\
+ }, function(args) return 'got ' .. args.value end)\n";
+
+/// The schema the adhoc tool with wire name `name` on `vm` binds.
+fn adhoc_schema(vm: &crate::SectionVm, name: &str) -> Json {
+ vm.adhoc_tools()
+ .binding(name)
+ .expect("the adhoc tools read")
+ .unwrap_or_else(|| panic!("{name} is defined"))
+ .schema()
+ .clone()
+}
+
+#[test]
+fn the_returned_object_is_the_tools_object_and_is_rendered_only_once_offered() {
+ let vm = lua_over(offer_set());
+ let fields: (bool, String, String, String, bool, bool) = vm.eval(&format!(
+ "{GRAB}\
+ return grab == tools.get('adhoc/grab'), grab.id, grab.description, \
+ grab.parameters.properties.value.type, grab.pack == tools.packs.get('adhoc'), \
+ grab.pack.tools[1] == grab"
+ ));
+ assert_eq!(
+ fields,
+ (
+ true,
+ "adhoc/grab".to_owned(),
+ "Grab a value".to_owned(),
+ "string".to_owned(),
+ true,
+ true
+ )
+ );
+ assert!(scoped(&vm).is_empty(), "defining a tool offers nothing");
+ vm.exec("tools.offer(tools.get('adhoc/grab'))");
+ assert_eq!(scoped(&vm), ["grab"]);
+}
+
+#[test]
+fn the_id_lowercases_the_name_and_the_wire_name_keeps_it() {
+ let vm = lua_over(offer_set());
+ let id: String = vm.eval(
+ "local shout = tools.adhoc({ name = 'Shout', description = 'Uppercase text', \
+ parameters = { text = 'string' } }, function(args) return args.text:upper() end)\n\
+ tools.offer(shout)\n\
+ assert(tools.get('adhoc/shout') == shout)\n\
+ return shout.id",
+ );
+ assert_eq!(id, "adhoc/shout");
+ assert_eq!(
+ scoped(&vm),
+ ["Shout"],
+ "the wire name is the name as written"
+ );
+}
+
+#[test]
+fn each_refusal_raises_on_the_defining_line() {
+ let vm = lua_over(offer_set());
+ vm.exec(GRAB);
+ let invalid = "tools.adhoc: invalid name \"1x\": expected [A-Za-z][A-Za-z0-9_-]{0,63}";
+ for (call, expected) in [
+ (
+ "tools.adhoc('grab', function() end)",
+ "tools.adhoc takes an attrs table first, got string",
+ ),
+ (
+ "tools.adhoc({ name = 'x', description = 'y' })",
+ "tools.adhoc takes the tool's function second, got nil",
+ ),
+ (
+ "tools.adhoc({ name = 'x', description = 'y' }, function() end, 'z')",
+ "tools.adhoc takes two arguments, got extra string",
+ ),
+ (
+ "tools.adhoc({ name = 'grab', description = 'again' }, function() end)",
+ "tools.adhoc name \"grab\" is already registered",
+ ),
+ (
+ "tools.adhoc({ name = 'GRAB', description = 'again' }, function() end)",
+ "tools.adhoc name \"GRAB\" has the id adhoc/grab, which \"grab\" already holds",
+ ),
+ (
+ "tools.adhoc({ name = 'x', description = 'y', run = 1 }, function() end)",
+ "tools.adhoc: unknown key \"run\"; accepted keys are name, description, parameters",
+ ),
+ (
+ "tools.adhoc({ description = 'y' }, function() end)",
+ "tools.adhoc: \"name\" is required",
+ ),
+ (
+ "tools.adhoc({ name = 'x' }, function() end)",
+ "tools.adhoc: \"description\" is required",
+ ),
+ (
+ "tools.adhoc({ name = 7, description = 'y' }, function() end)",
+ "tools.adhoc: \"name\" must be a string, got integer",
+ ),
+ (
+ "tools.adhoc({ name = 'x', description = false }, function() end)",
+ "tools.adhoc: \"description\" must be a string, got boolean",
+ ),
+ (
+ "tools.adhoc({ name = '1x', description = 'y' }, function() end)",
+ invalid,
+ ),
+ (
+ "tools.adhoc({ name = 'x', description = 'y', parameters = 'string' }, function() end)",
+ "tools.adhoc: parameters must be a table, got string",
+ ),
+ (
+ "tools.adhoc({ name = 'x', description = 'y', parameters = { p = 'table' } }, \
+ function() end)",
+ "tools.adhoc: param \"p\" has unsupported type \"table\"",
+ ),
+ (
+ "tools.adhoc({ name = 'x', description = 'y', \
+ parameters = { type = 'object', properties = { q = function() end } } }, \
+ function() end)",
+ "tools.adhoc: parameters schema cannot be encoded as JSON: value.properties.q \
+ must be JSON data, got function",
+ ),
+ ] {
+ let error = raised(&vm, call);
+ assert!(error.contains(expected), "{call}: {error}");
+ }
+ let ids: Vec = vm
+ .adhoc_tools()
+ .bindings()
+ .expect("the adhoc tools read")
+ .iter()
+ .map(|binding| binding.id().to_string())
+ .collect();
+ assert_eq!(ids, ["adhoc/grab"], "no refused definition registers");
+}
+
+#[test]
+fn a_definition_whose_tool_object_cannot_be_stored_leaves_no_tool_behind() {
+ let vm = lua_over(offer_set());
+ let lua = vm.lua();
+ let objects: Table = lua
+ .named_registry_value(TOOL_OBJECTS_REGISTRY)
+ .expect("the tool-object table is installed");
+ lua.set_named_registry_value(TOOL_OBJECTS_REGISTRY, false)
+ .expect("the tool-object registry value is replaced");
+ let defined: bool = vm.eval(
+ "return (pcall(tools.adhoc, { name = 'x', description = 'y' }, \
+ function() return 'z' end))",
+ );
+ assert!(!defined, "the object insert fails the definition");
+ lua.set_named_registry_value(TOOL_OBJECTS_REGISTRY, objects)
+ .expect("the tool-object table is restored");
+ assert_eq!(
+ vm.adhoc_tools()
+ .binding("adhoc/x")
+ .expect("the adhoc tools read"),
+ None,
+ "a failed definition registers nothing"
+ );
+ let same: bool = vm.eval(
+ "local x = tools.adhoc({ name = 'x', description = 'y' }, function() return 'z' end)\n\
+ return x == tools.get('adhoc/x')",
+ );
+ assert!(
+ same,
+ "a second definition stores the object tools.get reads"
+ );
+}
+
+#[test]
+fn parameters_take_the_short_form_a_json_schema_or_nothing() {
+ let vm = lua_over(offer_set());
+ vm.exec(
+ "tools.adhoc({ name = 'find', description = 'Find notes', \
+ parameters = { query = 'string', limit = { 'integer', 'maximum hits' } } }, \
+ function() end)\n\
+ tools.adhoc({ name = 'typed', description = 'Typed', \
+ parameters = { type = 'string' } }, function() end)\n\
+ tools.adhoc({ name = 'none', description = 'No parameters' }, function() end)",
+ );
+ assert_eq!(
+ adhoc_schema(&vm, "find"),
+ json!({
+ "type": "object",
+ "properties": {
+ "query": { "type": "string" },
+ "limit": { "type": "integer", "description": "maximum hits" }
+ },
+ "required": ["limit", "query"]
+ })
+ );
+ assert_eq!(
+ adhoc_schema(&vm, "typed"),
+ json!({
+ "type": "object",
+ "properties": { "type": { "type": "string" } },
+ "required": ["type"]
+ }),
+ "a type other than object makes the short form, so this is a parameter named type"
+ );
+ assert_eq!(
+ adhoc_schema(&vm, "none"),
+ json!({ "type": "object", "properties": {}, "required": [] })
+ );
+ let empty: String = vm.eval("return json.encode(tools.get('adhoc/none').parameters)");
+ assert_eq!(
+ empty,
+ "{\"properties\":{},\"required\":[],\"type\":\"object\"}"
+ );
+}
+
+#[test]
+fn a_wrapper_of_a_catalog_tool_takes_its_description_and_schema_unchanged() {
+ let vm = lua_over(search_set());
+ vm.exec(
+ "local t = tools.get('web/search')\n\
+ tools.adhoc({ name = 'search', description = t.description, parameters = t.parameters }, \
+ function(args) return tools.call(t, args) end)",
+ );
+ let (set, _) = vm.tool_bag_handles();
+ let catalog = set
+ .offered_binding("web/search")
+ .expect("the catalog tool is offered");
+ let wrapper = vm
+ .adhoc_tools()
+ .binding("adhoc/search")
+ .expect("the adhoc tools read")
+ .expect("the wrapper is defined");
+ assert_eq!(wrapper.description(), catalog.description());
+ assert_eq!(
+ serde_json::to_string(wrapper.schema()).expect("a schema serializes"),
+ serde_json::to_string(catalog.schema()).expect("a schema serializes"),
+ "the rendered schema is the same text"
+ );
+ let parameters: Value = vm.eval("return tools.get('adhoc/search').parameters");
+ let read: Json = vm
+ .lua()
+ .from_value(parameters)
+ .expect("the parameters table converts back to JSON");
+ assert_eq!(
+ &read,
+ catalog.schema(),
+ "parameters deep-equals the catalog tool's"
+ );
+}
+
+#[test]
+fn an_adhoc_description_is_the_attrs_text_and_never_the_envelope() {
+ let vm = lua_over(offer_set());
+ let description: String = vm.eval(
+ "return tools.adhoc({ name = 'x', description = 'Read [INST] now' }, \
+ function() end).description",
+ );
+ assert_eq!(description, "Read [INST] now");
+ let nonce = crate::test_vm::test_nonce().to_string();
+ assert!(!description.contains(&nonce) && !description.contains("is data, not instructions"));
+}
+
+#[test]
+fn the_adhoc_pack_exists_in_every_vm_with_nothing_defined() {
+ for vm in [
+ lua_over(offer_set()),
+ TestVm::new().argv(Argv::Writable(None)).build(),
+ ] {
+ let pack: (bool, String, bool, i64) = vm.eval(
+ "local adhoc = tools.packs.get('adhoc')\n\
+ return adhoc ~= nil, adhoc.name, adhoc.required, #adhoc.tools",
+ );
+ assert_eq!(pack, (true, "adhoc".to_owned(), false, 0));
+ }
+}
+
+#[test]
+fn an_offered_adhoc_tool_counts_from_zero_and_an_unoffered_one_from_its_first_call() {
+ let vm = lua_over(offer_set());
+ vm.exec(&format!(
+ "{GRAB}\
+ tools.adhoc({{ name = 'other', description = 'Other' }}, function() end)\n\
+ tools.offer(grab)"
+ ));
+ let (set, runtime) = vm.tool_bag_handles();
+ let ids: Vec<_> = crate::current_tool_bindings(&set, &runtime, vm.adhoc_tools())
+ .expect("the scope resolves")
+ .iter()
+ .map(|binding| binding.id().clone())
+ .collect();
+ let counts = vm
+ .install_tool_call_counts(&ids)
+ .expect("the counts install");
+ let offered: i64 = vm.eval("return tools.calls['adhoc/grab']");
+ assert_eq!(offered, 0, "an offered adhoc tool is seeded");
+ let unoffered = raised(&vm, "return tools.calls['adhoc/other']");
+ assert!(
+ unoffered.contains(
+ "(an adhoc tool that was neither offered in this section nor called with tools.call)"
+ ),
+ "{unoffered}"
+ );
+ counts.ensure("adhoc/other").expect("a call seeds its id");
+ counts
+ .increment("adhoc/other")
+ .expect("the seeded id counts");
+ let called: i64 = vm.eval("return tools.calls['adhoc/other']");
+ assert_eq!(called, 1, "a call gives an unoffered adhoc tool its count");
+}
diff --git a/crates/runvil-internal/lua/src/tools/tests-offer-limits.rs b/crates/runvil-internal/lua/src/tools/tests-offer-limits.rs
new file mode 100644
index 000000000..662eb335d
--- /dev/null
+++ b/crates/runvil-internal/lua/src/tools/tests-offer-limits.rs
@@ -0,0 +1,77 @@
+//! Tests for the offer verbs' array length bound: an array longer than
+//! the held key limit is refused before any entry is read.
+
+use crate::test_vm::{lua_over, offer_set, offers, raised};
+
+#[test]
+fn a_len_of_maxinteger_is_refused_and_the_vm_still_offers() {
+ let vm = lua_over(offer_set());
+ let error = raised(
+ &vm,
+ "tools.offer(setmetatable({}, { __len = function() return math.maxinteger end }))",
+ );
+ assert!(
+ error.contains(
+ "tools.offer takes an array of at most 100000 entries, got 9223372036854775807"
+ ),
+ "the refusal names the bound and the reported length: {error}"
+ );
+ vm.exec("tools.offer('web')");
+ assert_eq!(
+ offers(&vm),
+ ["static:web"],
+ "the refused offer recorded nothing and the verb still works"
+ );
+}
+
+#[test]
+fn an_array_past_the_reference_stack_cap_is_refused() {
+ let vm = lua_over(offer_set());
+ let error = raised(
+ &vm,
+ "local t = {} for i = 1, 1200000 do t[i] = 'web' end tools.offer(t)",
+ );
+ assert!(
+ error.contains("got 1200000"),
+ "an array too long to hold one reference per entry is refused: {error}"
+ );
+ assert!(offers(&vm).is_empty(), "a refusal records nothing");
+}
+
+#[test]
+fn an_array_of_exactly_the_limit_is_accepted() {
+ let vm = lua_over(offer_set());
+ vm.exec("local t = {} for i = 1, 100000 do t[i] = 'web' end tools.offer(t)");
+ assert_eq!(
+ offers(&vm),
+ ["static:web"],
+ "an array at the bound is read whole"
+ );
+}
+
+#[test]
+fn offer_dynamic_refuses_an_array_one_past_the_limit() {
+ let vm = lua_over(offer_set());
+ let error = raised(
+ &vm,
+ "local t = {} for i = 1, 100001 do t[i] = 'web' end tools.offer_dynamic(t)",
+ );
+ assert!(
+ error.contains("tools.offer_dynamic takes an array of at most 100000 entries, got 100001"),
+ "the bound applies to both verbs and names the verb: {error}"
+ );
+ assert!(offers(&vm).is_empty(), "a refusal records nothing");
+}
+
+#[test]
+fn a_len_too_large_to_allocate_is_refused() {
+ let vm = lua_over(offer_set());
+ let error = raised(
+ &vm,
+ "tools.offer(setmetatable({}, { __len = function() return 1 << 40 end }))",
+ );
+ assert!(
+ error.contains("tools.offer takes an array of at most 100000 entries, got 1099511627776"),
+ "a length that would abort on allocation is refused first: {error}"
+ );
+}
diff --git a/crates/runvil-internal/lua/src/tools/tests-offering.rs b/crates/runvil-internal/lua/src/tools/tests-offering.rs
index b670de36b..7c91a0893 100644
--- a/crates/runvil-internal/lua/src/tools/tests-offering.rs
+++ b/crates/runvil-internal/lua/src/tools/tests-offering.rs
@@ -1,251 +1,349 @@
-//! Tests for the id-keyed `tools` namespace: tool objects, `tools.offer`
-//! over ids and tool objects, the `required` and `extras` lists,
-//! `tools.get`, and `tools.offer_local`.
+//! Tests for the offer verbs, `tools.offer` and `tools.offer_dynamic`:
+//! every accepted form, the string-shape rule, each refusal, the
+//! rendered-list refusal first, and the `tools` table they sit on.
use std::collections::BTreeMap;
-use mlua::{Lua, Value, Variadic};
-use runvil_types::packs::PackId;
-
+use crate::RenderedTools;
use crate::handles::ToolSet;
-use crate::test_vm::{lua_over, scoped, tool_at};
-use crate::tools::decode::collect_offer_entries;
-use crate::{RenderedTools, ToolBinding};
+use crate::test_vm::{lua_over, offer_set, offers, raised, scoped, tool_at};
-/// A set declaring the Pack `web` and offering its two tools beside the
-/// two of the undeclared Pack `gh`, in id order, under their wire names.
-fn offering_set() -> ToolSet {
- ToolSet::new(
- vec![PackId::parse("web").expect("`web` is a valid Pack id")],
- std::collections::BTreeMap::new(),
- vec![
- ToolBinding::from_info("gh_issues_list", &tool_at("gh/issues.list")),
- ToolBinding::from_info("gh_search", &tool_at("gh/search")),
- ToolBinding::from_info("web_fetch", &tool_at("web/fetch")),
- ToolBinding::from_info("web_search", &tool_at("web/search")),
- ],
+/// The adhoc tool `grab` the forms below offer as an object.
+const GRAB: &str =
+ "local grab = tools.adhoc({ name = 'grab', description = 'Grab a value' }, function() end)\n";
+
+/// Every accepted form, each line through `verb`.
+fn forms(verb: &str) -> String {
+ format!(
+ "{GRAB}\
+ assert(select('#', {verb}('web/search')) == 0, 'the verb returns nothing')\n\
+ {verb}('web')\n\
+ {verb}(grab)\n\
+ {verb}(tools.packs.get('web'))\n\
+ {verb}(tools.get('web/search').pack)\n\
+ {verb}({{ 'web/search', grab, 'subagents', tools.packs.get('user-input') }})\n\
+ {verb}(tools.packs.get('web').tools)\n\
+ {verb}(tools.packs.get('adhoc'))\n\
+ {verb}(tools.packs.extras())\n\
+ {verb}(tools.packs)\n\
+ {verb}()\n\
+ {verb}({{}})"
)
}
#[test]
-fn a_tool_object_reads_its_id_and_catalog_description_and_refuses_assignment() {
- let vm = lua_over(offering_set());
- let result: (String, String, bool, String) = vm.eval(
- "local tool = tools.get('gh/search')\n\
- tools.offer(tool)\n\
- local ok, err = pcall(function() tool.description = 'x' end)\n\
- return tool.id, tool.description, ok, tostring(err)",
- );
- assert_eq!(result.0, "gh/search");
- assert_eq!(
- result.1, "gh/search tool",
- "description is the catalog text"
- );
- assert!(!result.2, "assigning a field is refused");
- assert!(
- result
- .3
- .contains("Tool objects are frozen: cannot assign field \"description\""),
- "the refusal names the field: {}",
- result.3
+fn every_accepted_form_records_each_target_once_in_call_order_under_its_verbs_mode() {
+ for (verb, mode) in [
+ ("tools.offer", "static"),
+ ("tools.offer_dynamic", "dynamic"),
+ ] {
+ let vm = lua_over(offer_set());
+ vm.exec(&forms(verb));
+ let expected: Vec = [
+ "web/search",
+ "web",
+ "adhoc/grab",
+ "subagents",
+ "user-input",
+ "web/fetch",
+ "adhoc",
+ "gh",
+ ]
+ .iter()
+ .map(|target| format!("{mode}:{target}"))
+ .collect();
+ assert_eq!(
+ offers(&vm),
+ expected,
+ "{verb}: ids, Packs, objects, and arrays record their targets, an equal \
+ offer is skipped, and no argument or an empty array records nothing"
+ );
+ }
+}
+
+#[test]
+fn the_two_verbs_record_separately_so_the_same_target_takes_both_modes() {
+ let vm = lua_over(offer_set());
+ vm.exec(
+ "tools.offer('web')\n\
+ tools.offer_dynamic('web')\n\
+ tools.offer('web')",
);
+ assert_eq!(offers(&vm), ["static:web", "dynamic:web"]);
}
#[test]
-fn offer_decodes_ids_tool_objects_and_arrays_into_wire_names() {
- let vm = lua_over(offering_set());
+fn a_string_with_a_slash_is_a_tool_id_and_one_without_is_a_pack_id() {
+ let vm = lua_over(offer_set());
vm.exec(
- "tools.offer('web/search')\n\
- tools.offer(tools.get('gh/search'))\n\
- tools.offer({ 'gh/issues.list', tools.get('web/fetch'), 'web/search' })\n\
- tools.offer()",
+ "tools.adhoc({ name = 'Shout', description = 'Uppercase text' }, function() end)\n\
+ tools.offer('web/search')\n\
+ tools.offer('gh')\n\
+ tools.offer('adhoc/shout')\n\
+ tools.offer('adhoc')",
);
assert_eq!(
- scoped(&vm),
- ["web_search", "gh_search", "gh_issues_list", "web_fetch"],
- "each tool enters the scope once, under its wire name, in first-offer order"
+ offers(&vm),
+ [
+ "static:web/search",
+ "static:gh",
+ "static:adhoc/shout",
+ "static:adhoc"
+ ]
+ );
+ let pack = |name: &str| {
+ format!(
+ "tools.offer: no Pack named \"{name}\" in this run; declare it under uses: to \
+ require it, or offer it only when tools.packs.get(\"{name}\") returns it"
+ )
+ };
+ for (call, expected) in [
+ ("tools.offer('Web')", pack("Web")),
+ (
+ "tools.offer('Shout')",
+ format!("{} (did you mean 'adhoc/shout'?)", pack("Shout")),
+ ),
+ (
+ "tools.offer('web//x')",
+ "tools.offer: \"web//x\" is not a tool in this run".to_owned(),
+ ),
+ (
+ "tools.offer('adhoc/other')",
+ "tools.offer: \"adhoc/other\" is not a tool in this run".to_owned(),
+ ),
+ ] {
+ let error = raised(&vm, call);
+ assert!(
+ error.contains(&expected),
+ "an invalid id takes the message of an unknown one of its shape: {call}: {error}"
+ );
+ }
+}
+
+#[test]
+fn a_catalog_tool_object_under_the_adhoc_pack_is_refused_as_an_unknown_tool() {
+ let catalog_adhoc = crate::ToolBinding::from_info("adhoc_x", &tool_at("adhoc/x"));
+ let vm = lua_over(ToolSet::new(
+ Vec::new(),
+ BTreeMap::new(),
+ vec![catalog_adhoc],
+ ));
+ let error: String = vm.eval(
+ "local ok, err = pcall(tools.offer, tools.get('adhoc/x'))\n\
+ assert(not ok, 'offering the catalog adhoc/x object raises')\n\
+ return tostring(err)",
+ );
+ assert!(
+ error.contains("tools.offer: \"adhoc/x\" is not a tool in this run"),
+ "the object takes the string form's message: {error}"
+ );
+ assert!(offers(&vm).is_empty(), "the refused offer records nothing");
+ assert!(
+ scoped(&vm).is_empty(),
+ "the scope resolves without an adhoc/x binding"
);
}
#[test]
-fn offer_records_nothing_when_any_entry_is_not_a_catalog_tool() {
- for bad in ["gh/missing", "Not An Id", "gh_search", "helper"] {
- let vm = lua_over(offering_set());
- vm.exec("tools.offer_local('helper', 'a local helper', {}, function() return '' end)");
- let error: String = vm.eval(&format!(
- "local ok, err = pcall(tools.offer, {{ 'web/search', {bad:?} }})\n\
- assert(not ok, 'the bad entry is refused')\n\
- return tostring(err)"
- ));
- assert!(
- error.contains(&format!(
- "tools.offer: {bad:?} is not a catalog tool in this run"
- )),
- "tools.offer names {bad:?}: {error}"
+fn each_refusal_names_its_verb_and_a_refused_call_records_nothing() {
+ for verb in ["tools.offer", "tools.offer_dynamic"] {
+ let vm = lua_over(offer_set());
+ let unknown_pack = |name: &str| {
+ format!(
+ "{verb}: no Pack named \"{name}\" in this run; declare it under uses: to \
+ require it, or offer it only when tools.packs.get(\"{name}\") returns it"
+ )
+ };
+ let shape = format!(
+ "{verb} takes tool ids, Pack ids, tool objects, Pack objects, or an array of them, got"
+ );
+ let entry = format!(
+ "{verb} takes tool ids, Pack ids, tool objects, or Pack objects in an array, got"
);
+ let unavailable =
+ format!("{verb}: the mcp Pack is unavailable in this run: the mcp server is down");
+ for (call, expected) in [
+ ("'wbe'", unknown_pack("wbe")),
+ (
+ "'web_search'",
+ format!(
+ "{} (did you mean 'web/search'?)",
+ unknown_pack("web_search")
+ ),
+ ),
+ (
+ "'web/serch'",
+ format!("{verb}: \"web/serch\" is not a tool in this run"),
+ ),
+ ("'mcp'", unavailable.clone()),
+ (
+ "'web/search', 'web/fetch'",
+ format!("{verb} takes one tool or Pack, or an array of them, got extra string"),
+ ),
+ ("42", format!("{shape} integer")),
+ ("nil", format!("{shape} nil")),
+ ("tools.get('web/serch')", format!("{shape} nil")),
+ ("messages", format!("{shape} userdata")),
+ (
+ "{ 'web', nil, 'mcp' }",
+ format!("{verb} takes an array, got a table with the key 3"),
+ ),
+ (
+ "setmetatable({ 'web' }, { __len = function() return 2 end })",
+ format!("{entry} nil at index 2"),
+ ),
+ ("{ { 'web' } }", format!("{entry} table at index 1")),
+ ("{ 'web', 42 }", format!("{entry} integer at index 2")),
+ (
+ "{ name = 'web' }",
+ format!("{verb} takes an array, got a table with the key name"),
+ ),
+ (
+ "setmetatable({ 'web' }, { __len = function() return 0 end })",
+ format!("{verb} takes an array, got a table with the key 1"),
+ ),
+ ("{ 'web', 'mcp' }", unavailable.clone()),
+ ("{ 'web/search', 'wbe' }", unknown_pack("wbe")),
+ ] {
+ let error = raised(&vm, &format!("{verb}({call})"));
+ assert!(error.contains(&expected), "{verb}({call}): {error}");
+ }
assert!(
- scoped(&vm).is_empty(),
- "a refused call records no entry, the valid one included ({bad:?})"
+ offers(&vm).is_empty(),
+ "{verb}: a refused call records no entry, its valid ones included"
);
}
}
#[test]
-fn offering_a_tool_object_matches_offering_its_id() {
- let by_object = lua_over(offering_set());
- by_object.exec("tools.offer(tools.get('gh/search'))");
- let by_id = lua_over(offering_set());
- by_id.exec("tools.offer('gh/search')");
- assert_eq!(scoped(&by_object), scoped(&by_id));
- assert_eq!(scoped(&by_id), ["gh_search"]);
+fn an_array_is_read_through_its_metamethods() {
+ let vm = lua_over(offer_set());
+ vm.exec(
+ "local entries = { 'gh', 'web/fetch' }\n\
+ tools.offer(setmetatable({}, {\n\
+ __len = function() return #entries end,\n\
+ __index = function(_, i) return entries[i] end,\n\
+ }))",
+ );
+ assert_eq!(offers(&vm), ["static:gh", "static:web/fetch"]);
}
#[test]
-fn required_and_extras_split_the_offering_by_declared_pack_and_share_objects() {
- let vm = lua_over(offering_set());
- let result: (String, String, bool, bool, bool, bool) = vm.eval(
- "local function ids(list)\n\
- local out = {}\n\
- for i, tool in ipairs(list) do out[i] = tool.id end\n\
- return table.concat(out, ',')\n\
- end\n\
- local required, extras = tools.required(), tools.extras()\n\
- return ids(required), ids(extras), \
- required[1] == tools.get('web/fetch'), \
- extras[2] == tools.get('gh/search'), \
- tools.required() ~= required, \
- tools.required()[2] == required[2]",
+fn the_render_refusal_comes_before_every_other_check_and_defining_still_works() {
+ let vm = lua_over(offer_set());
+ vm.exec("tools.offer('web/search')");
+ vm.messages().attach_rendered_tools(RenderedTools {
+ schemas: Vec::new(),
+ dispatch: BTreeMap::new(),
+ dynamic: Vec::new(),
+ });
+ for verb in ["tools.offer", "tools.offer_dynamic"] {
+ for args in ["'gh'", "'web/search'", "'wbe'", "42", "", "'web', 'gh'"] {
+ let error = raised(&vm, &format!("{verb}({args})"));
+ assert!(
+ error.contains(&format!(
+ "{verb}: the section's tool list is fixed at its first models.loop \
+ round; make every offer before the first loop, or offer in another section"
+ )),
+ "{verb}({args}) raises the fixed-list refusal first: {error}"
+ );
+ }
+ }
+ let defined: bool = vm.eval(
+ "local late = tools.adhoc({ name = 'late', description = 'Late' }, function() end)\n\
+ return tools.get('adhoc/late') == late",
);
+ assert!(defined, "defining an adhoc tool works after the render");
assert_eq!(
- result,
- (
- "web/fetch,web/search".to_owned(),
- "gh/issues.list,gh/search".to_owned(),
- true,
- true,
- true,
- true,
- ),
- "a declared Pack's tools are required, the rest extras, both in id \
- order, every list a fresh array of the same shared objects"
+ offers(&vm),
+ ["static:web/search"],
+ "no refused offer records"
);
}
#[test]
-fn tools_get_reads_one_object_by_id_and_nil_for_anything_else() {
- let vm = lua_over(offering_set());
- let result: (String, bool, bool, bool, bool, String) = vm.eval(
- "tools.offer_local('helper', 'a local helper', {}, function() return '' end)\n\
- local ok, err = pcall(tools.get, 42)\n\
- assert(not ok, 'a non-string is refused')\n\
- return tools.get('gh/search').id, tools.get('gh/missing') == nil, \
- tools.get('helper') == nil, tools.get('Not An Id') == nil, \
- tools.get('gh_search') == nil, tostring(err)",
+fn offering_every_pack_or_the_extras_offers_their_tools() {
+ let every = lua_over(offer_set());
+ every.exec(
+ "tools.adhoc({ name = 'grab', description = 'Grab a value' }, function() end)\n\
+ tools.offer(tools.packs)",
);
- assert_eq!(result.0, "gh/search");
- assert!(
- result.1 && result.2 && result.3 && result.4,
- "a miss, a local alias, a malformed id, and a wire name all read nil: {result:?}"
+ assert_eq!(
+ scoped(&every),
+ [
+ "grab",
+ "gh_issues_list",
+ "gh_search",
+ "user-input_ask",
+ "web_fetch",
+ "web_search"
+ ],
+ "every Pack, the adhoc Pack included, in name order"
);
- assert!(
- result.5.contains("tools.get takes a tool id, got integer"),
- "the refusal names the type: {}",
- result.5
+ let extras = lua_over(offer_set());
+ extras.exec(
+ "tools.adhoc({ name = 'grab', description = 'Grab a value' }, function() end)\n\
+ tools.offer(tools.packs.extras())",
+ );
+ assert_eq!(
+ scoped(&extras),
+ ["gh_issues_list", "gh_search"],
+ "only the undeclared Packs, never the adhoc Pack"
);
}
#[test]
-fn offer_local_registers_a_local_tool_and_names_itself_in_its_errors() {
- let vm = lua_over(offering_set());
- let errors: (String, String, String) = vm.eval(
- "tools.offer_local('gh_search', 'a local search', {}, function() return '' end)\n\
- local _, duplicate = pcall(tools.offer_local, 'gh_search', 'again', {}, function() end)\n\
- local _, param = pcall(tools.offer_local, 'other', 'x', { p = 'table' }, function() end)\n\
- local _, alias = pcall(tools.offer_local, 'web/search', 'x', {}, function() end)\n\
- return tostring(duplicate), tostring(param), tostring(alias)",
- );
- assert!(
- errors
- .0
- .contains("tools.offer_local alias \"gh_search\" is already registered"),
- "{}",
- errors.0
+fn a_tool_object_reads_its_id_and_catalog_description_and_refuses_assignment() {
+ let vm = lua_over(offer_set());
+ let result: (String, String, bool, String) = vm.eval(
+ "local tool = tools.get('gh/search')\n\
+ tools.offer(tool)\n\
+ local ok, err = pcall(function() tool.description = 'x' end)\n\
+ return tool.id, tool.description, ok, tostring(err)",
);
- assert!(
- errors
- .1
- .contains("tools.offer_local param \"p\" has unsupported type \"table\""),
- "{}",
- errors.1
+ assert_eq!(result.0, "gh/search");
+ assert_eq!(
+ result.1, "gh/search tool",
+ "description is the catalog text"
);
+ assert!(!result.2, "assigning a field is refused");
assert!(
- errors.2.contains("invalid alias \"web/search\""),
- "a local alias keeps the alias grammar: {}",
- errors.2
+ result
+ .3
+ .contains("Tool objects are frozen: cannot assign field \"description\""),
+ "the refusal names the field: {}",
+ result.3
);
}
#[test]
-fn every_offer_function_raises_once_the_tool_list_is_rendered_before_any_other_check() {
- let vm = lua_over(offering_set());
- vm.exec(
- "tools.offer('web/search')\n\
- packs.offer('web')\n\
- tools.offer_local('helper', 'a local helper', {}, function() return '' end)",
+fn tools_get_reads_one_object_by_id_and_nil_for_anything_else() {
+ let vm = lua_over(offer_set());
+ let result: (String, bool, bool, bool, bool, bool, String) = vm.eval(
+ "local helper = tools.adhoc({ name = 'helper', description = 'A helper' }, function() end)\n\
+ local ok, err = pcall(tools.get, 42)\n\
+ assert(not ok, 'a non-string is refused')\n\
+ return tools.get('gh/search').id, tools.get('adhoc/helper') == helper, \
+ tools.get('gh/missing') == nil, tools.get('helper') == nil, \
+ tools.get('Not An Id') == nil, tools.get('gh_search') == nil, tostring(err)",
);
- let before = scoped(&vm);
- vm.messages().attach_rendered_tools(RenderedTools {
- schemas: Vec::new(),
- dispatch: BTreeMap::new(),
- });
- let refusals: Vec = vm.eval(
- "local out = {}\n\
- for _, offer in ipairs({\n\
- function() tools.offer('gh/search') end,\n\
- function() tools.offer('web/search') end,\n\
- function() tools.offer('gh/missing') end,\n\
- function() packs.offer('web') end,\n\
- function() packs.offer('nope') end,\n\
- function() tools.offer_local('other', 'x', {}, function() return '' end) end,\n\
- function() tools.offer_local('helper', 'again', {}, function() return '' end) end,\n\
- function() tools.offer_local() end,\n\
- }) do\n\
- local ok, err = pcall(offer)\n\
- out[#out + 1] = ok and 'accepted' or tostring(err)\n\
- end\n\
- return out",
+ assert_eq!(result.0, "gh/search");
+ assert!(result.1, "an adhoc tool reads by its id");
+ assert!(
+ result.2 && result.3 && result.4 && result.5,
+ "a miss, an adhoc tool's wire name, a malformed id, and a catalog wire name \
+ all read nil: {result:?}"
);
- let fixed = "the section's tool list is fixed at its first models.loop round; make every \
- offer before the first loop, or offer in another section";
- let calls = [
- "tools.offer",
- "tools.offer",
- "tools.offer",
- "packs.offer",
- "packs.offer",
- "tools.offer_local",
- "tools.offer_local",
- "tools.offer_local",
- ];
- assert_eq!(refusals.len(), calls.len(), "{refusals:?}");
- for (refusal, call) in refusals.iter().zip(calls) {
- assert!(
- refusal.contains(&format!("{call}: {fixed}")),
- "a new, a repeated, and an unknown entry, and a missing argument, all \
- raise the fixed-list refusal first: {refusal}"
- );
- }
- assert_eq!(scoped(&vm), before, "no refused offer reaches the scope");
assert!(
- !vm.has_local_tool("other")
- .expect("the local-tools registry reads"),
- "no refused local offer registers"
+ result.6.contains("tools.get takes a tool id, got integer"),
+ "the refusal names the type: {}",
+ result.6
);
}
#[test]
-fn the_tools_namespace_holds_exactly_its_five_functions() {
- let vm = lua_over(offering_set());
+fn the_tools_table_holds_exactly_its_api() {
+ let vm = lua_over(offer_set());
let keys: String = vm.eval(
"local keys = {}\n\
for key, value in pairs(tools) do keys[#keys + 1] = key .. ':' .. type(value) end\n\
@@ -253,43 +351,7 @@ fn the_tools_namespace_holds_exactly_its_five_functions() {
return table.concat(keys, ',')",
);
assert_eq!(
- keys, "extras:function,get:function,offer:function,offer_local:function,required:function",
- "the tools table holds exactly the namespace's functions"
+ keys, "adhoc:function,get:function,offer:function,offer_dynamic:function,packs:table",
+ "the tools table holds exactly the namespace's members before the shim installs call"
);
}
-
-#[test]
-fn tools_entries_name_the_calling_function_in_every_shape_error() {
- let lua = Lua::new();
- let string = |text: &str| {
- Value::String(
- lua.create_string(text)
- .expect("a fresh VM creates a short string"),
- )
- };
- let array = lua
- .create_sequence_from(vec![string("web/search")])
- .expect("a fresh VM creates the offer array");
- for (args, fragment) in [
- (
- vec![Value::Integer(42)],
- "tools.offer takes tool ids, tool objects, or arrays of them, got integer",
- ),
- (
- vec![string("web/search"), string("x")],
- "tools.offer takes one tool or a list of them, got extra string",
- ),
- (
- vec![Value::Table(array), string("x")],
- "tools.offer takes one tool or a list of them, got extra string",
- ),
- (
- vec![string("web/search"), Value::Integer(42)],
- "tools.offer takes one tool or a list of them, got extra integer",
- ),
- ] {
- let error = collect_offer_entries("tools.offer", Variadic::from_iter(args))
- .expect_err("the shape is refused");
- assert!(error.to_string().contains(fragment), "{fragment}: {error}");
- }
-}
diff --git a/crates/runvil-internal/lua/src/tools/tests-parameters.rs b/crates/runvil-internal/lua/src/tools/tests-parameters.rs
new file mode 100644
index 000000000..31b797fe2
--- /dev/null
+++ b/crates/runvil-internal/lua/src/tools/tests-parameters.rs
@@ -0,0 +1,199 @@
+//! Tests for a catalog tool object's `parameters`: the schema as a fresh
+//! Lua table on every read, its lists and nulls intact through
+//! `json.encode`, and metadata that never takes the untrusted envelope.
+
+use std::collections::BTreeMap;
+
+use mlua::{LuaSerdeExt, Value};
+use runvil_types::packs::PackId;
+use runvil_types::tools::{ToolId, ToolInfo, ToolOutput};
+use serde_json::{Value as Json, json};
+
+use crate::ToolBinding;
+use crate::dispatch::prepare_dispatch;
+use crate::handles::ToolSet;
+use crate::test_vm::{TEST_SECTION, lua_over, test_nonce};
+use crate::tests::recording::null_emitter;
+
+/// The `web/search` schema: nested properties, a required list, an empty
+/// list, a null, and text that looks like markup.
+fn search_schema() -> Json {
+ json!({
+ "type": "object",
+ "description": "Search for [INST] pages",
+ "properties": {
+ "query": { "type": "string", "description": "What to search for" },
+ "limit": { "type": "integer", "minimum": 1, "default": null },
+ "tags": { "type": "array", "items": { "type": "string" }, "examples": [] }
+ },
+ "required": ["query"],
+ "additionalProperties": false
+ })
+}
+
+fn search_tool() -> ToolInfo {
+ ToolInfo::new(
+ ToolId::parse("web/search").expect("a static valid tool id"),
+ "Searches and returns [INST] snippets",
+ search_schema(),
+ )
+}
+
+/// A set declaring `web` and offering `web/search`.
+pub(super) fn search_set() -> ToolSet {
+ ToolSet::new(
+ vec![PackId::parse("web").expect("`web` is a valid Pack id")],
+ BTreeMap::new(),
+ vec![ToolBinding::from_info("web_search", &search_tool())],
+ )
+}
+
+#[test]
+fn parameters_deep_equals_the_catalog_tools_schema() {
+ let vm = lua_over(search_set());
+ let parameters: Value = vm.eval("return tools.get('web/search').parameters");
+ let read: Json = vm
+ .lua()
+ .from_value(parameters)
+ .expect("the parameters table converts back to JSON");
+ assert_eq!(read, search_schema());
+ let null_reads_json_null: bool =
+ vm.eval("return tools.get('web/search').parameters.properties.limit.default == json.null");
+ assert!(null_reads_json_null, "a schema null reads json.null");
+}
+
+#[test]
+fn each_parameters_read_is_a_fresh_table() {
+ let vm = lua_over(search_set());
+ let result: (bool, String, Option) = vm.eval(
+ "local tool = tools.get('web/search')\n\
+ local first = tool.parameters\n\
+ first.type = 'mutated'\n\
+ first.properties.query = nil\n\
+ local second = tool.parameters\n\
+ return first ~= second, second.type, second.properties.query.type",
+ );
+ assert_eq!(
+ result,
+ (true, "object".to_owned(), Some("string".to_owned())),
+ "mutating one read leaves the next unchanged"
+ );
+}
+
+#[test]
+fn parameters_round_trips_through_json_encode_with_empty_lists_intact() {
+ let vm = lua_over(search_set());
+ let encoded: String = vm.eval("return json.encode(tools.get('web/search').parameters)");
+ assert!(
+ encoded.contains("\"examples\":[]"),
+ "an empty list encodes as []: {encoded}"
+ );
+ assert!(
+ encoded.contains("\"default\":null"),
+ "a null encodes as null: {encoded}"
+ );
+ let decoded: Json = serde_json::from_str(&encoded).expect("json.encode writes JSON");
+ assert_eq!(decoded, search_schema());
+}
+
+#[test]
+fn assigning_parameters_raises() {
+ let vm = lua_over(search_set());
+ let error: String = vm.eval(
+ "local ok, err = pcall(function() tools.get('web/search').parameters = {} end)\n\
+ assert(not ok, 'assigning parameters is refused')\n\
+ return tostring(err)",
+ );
+ assert!(
+ error.contains("Tool objects are frozen: cannot assign field \"parameters\""),
+ "the refusal names the field: {error}"
+ );
+}
+
+#[test]
+fn a_tool_object_holds_exactly_id_description_parameters_and_pack() {
+ let vm = lua_over(search_set());
+ let fields: (String, bool, bool, String) = vm.eval(
+ "local tool = tools.get('web/search')\n\
+ return tool.id, type(tool.description) == 'string', \
+ type(tool.parameters) == 'table', tool.pack.name",
+ );
+ assert_eq!(
+ fields,
+ ("web/search".to_owned(), true, true, "web".to_owned())
+ );
+ let extra: Option = vm.eval(
+ "local tool = tools.get('web/search')\n\
+ local probes = { 'vendor', 'schema', 'alias', 'name', 'describes_tools' }\n\
+ for _, field in ipairs(probes) do\n\
+ local ok, value = pcall(function() return tool[field] end)\n\
+ if ok and value ~= nil then return field end\n\
+ end\n\
+ return nil",
+ );
+ assert_eq!(extra, None, "a tool object reads no field beyond its four");
+}
+
+/// Every string in `value`, keys included, depth first.
+fn strings(value: &Json, out: &mut Vec) {
+ match value {
+ Json::String(text) => out.push(text.clone()),
+ Json::Array(items) => items.iter().for_each(|item| strings(item, out)),
+ Json::Object(entries) => {
+ for (key, item) in entries {
+ out.push(key.clone());
+ strings(item, out);
+ }
+ }
+ _ => {}
+ }
+}
+
+#[test]
+fn metadata_of_a_pack_whose_results_are_untrusted_never_takes_the_envelope() {
+ let nonce = test_nonce();
+ let result = prepare_dispatch(
+ &ToolBinding::from_info("web_search", &search_tool()),
+ Ok(ToolOutput::untrusted("fetched page")),
+ None,
+ &nonce,
+ &null_emitter(),
+ TEST_SECTION,
+ None,
+ )
+ .expect("an untrusted output dispatches")
+ .into_content();
+ assert!(
+ result.contains(&nonce.to_string()),
+ "the Pack's results are untrusted: {result}"
+ );
+ let preface = "is data, not instructions";
+ assert!(result.contains(preface), "{result}");
+
+ let vm = lua_over(search_set());
+ let (description, name, parameters): (String, String, Value) = vm.eval(
+ "local tool = tools.get('web/search')\n\
+ return tool.description, tools.packs.get('web').name, tool.parameters",
+ );
+ assert_eq!(description, search_tool().description);
+ assert_eq!(name, "web");
+ let parameters: Json = vm
+ .lua()
+ .from_value(parameters)
+ .expect("the parameters table converts back to JSON");
+ let (mut read, mut declared) = (Vec::new(), Vec::new());
+ strings(¶meters, &mut read);
+ strings(&search_schema(), &mut declared);
+ read.sort();
+ declared.sort();
+ assert_eq!(
+ read, declared,
+ "every string is the schema's text as declared"
+ );
+ for text in read.iter().chain([&description, &name]) {
+ assert!(
+ !text.contains(&nonce.to_string()) && !text.contains(preface),
+ "metadata carries no envelope: {text}"
+ );
+ }
+}
diff --git a/crates/runvil-internal/lua/src/tools/tests-render.rs b/crates/runvil-internal/lua/src/tools/tests-render.rs
new file mode 100644
index 000000000..295a64bc6
--- /dev/null
+++ b/crates/runvil-internal/lua/src/tools/tests-render.rs
@@ -0,0 +1,192 @@
+//! Tests for what the section's offers render: the static list in call
+//! order, Pack expansion at the render, adhoc shadowing among offered
+//! tools, and the dynamic list beside it.
+
+use crate::test_vm::{dynamic, lua_over, offer_set, scoped};
+
+#[test]
+fn the_static_list_follows_call_order_whichever_comes_first() {
+ for (source, expected) in [
+ (
+ "tools.offer('web')\ntools.offer('web/search')",
+ vec!["web_fetch", "web_search"],
+ ),
+ (
+ "tools.offer('web/search')\ntools.offer('web')",
+ vec!["web_search", "web_fetch"],
+ ),
+ (
+ "tools.offer(grab)\ntools.offer('web')",
+ vec!["grab", "web_fetch", "web_search"],
+ ),
+ ] {
+ let vm = lua_over(offer_set());
+ vm.exec(&format!(
+ "local grab = tools.adhoc({{ name = 'grab', description = 'Grab a value' }}, \
+ function() end)\n{source}"
+ ));
+ assert_eq!(scoped(&vm), expected, "{source}");
+ }
+}
+
+#[test]
+fn repeated_offers_neither_duplicate_nor_move_a_tool() {
+ let vm = lua_over(offer_set());
+ vm.exec(
+ "tools.offer('web/fetch')\n\
+ tools.offer('gh')\n\
+ tools.offer('web')\n\
+ tools.offer('web/fetch')\n\
+ tools.offer({ 'gh/search', tools.packs.get('gh') })",
+ );
+ assert_eq!(
+ scoped(&vm),
+ ["web_fetch", "gh_issues_list", "gh_search", "web_search"],
+ "a tool followed by its Pack keeps the tool's place, and no repeat moves it"
+ );
+}
+
+#[test]
+fn the_adhoc_pack_expands_at_the_render_while_its_tools_array_is_read_at_the_call() {
+ let by_pack = lua_over(offer_set());
+ by_pack.exec(
+ "tools.adhoc({ name = 'zeta', description = 'Z' }, function() end)\n\
+ tools.offer(tools.packs.get('adhoc'))\n\
+ tools.adhoc({ name = 'alpha', description = 'A' }, function() end)",
+ );
+ assert_eq!(
+ scoped(&by_pack),
+ ["alpha", "zeta"],
+ "a Pack offer takes every adhoc tool defined before the render, in id order"
+ );
+ let by_tools = lua_over(offer_set());
+ by_tools.exec(
+ "tools.adhoc({ name = 'zeta', description = 'Z' }, function() end)\n\
+ tools.offer(tools.packs.get('adhoc').tools)\n\
+ tools.adhoc({ name = 'alpha', description = 'A' }, function() end)",
+ );
+ assert_eq!(
+ scoped(&by_tools),
+ ["zeta"],
+ "a tools array takes only the tools defined when it was read"
+ );
+}
+
+#[test]
+fn an_offered_adhoc_tool_shadows_an_offered_catalog_tool_of_its_wire_name() {
+ let shadowed = lua_over(offer_set());
+ shadowed.exec(
+ "tools.offer('web')\n\
+ tools.offer(tools.adhoc({ name = 'web_search', description = 'Mine' }, function() end))",
+ );
+ assert_eq!(scoped(&shadowed), ["web_fetch", "web_search"]);
+ let (set, runtime) = shadowed.tool_bag_handles();
+ let bound = crate::current_tool_bindings(&set, &runtime, shadowed.adhoc_tools())
+ .expect("the scope resolves");
+ assert_eq!(
+ bound[1].id().to_string(),
+ "adhoc/web_search",
+ "the adhoc tool is rendered and the catalog tool dropped where it was offered"
+ );
+ let unoffered = lua_over(offer_set());
+ unoffered.exec(
+ "tools.adhoc({ name = 'web_search', description = 'Mine' }, function() end)\n\
+ tools.offer('web')",
+ );
+ let (set, runtime) = unoffered.tool_bag_handles();
+ let ids: Vec = crate::current_tool_bindings(&set, &runtime, unoffered.adhoc_tools())
+ .expect("the scope resolves")
+ .iter()
+ .map(|binding| binding.id().to_string())
+ .collect();
+ assert_eq!(
+ ids,
+ ["web/fetch", "web/search"],
+ "a defined but unoffered adhoc tool shadows nothing"
+ );
+}
+
+#[test]
+fn the_dynamic_list_keeps_what_the_static_list_lacks_in_offer_order_once() {
+ for source in [
+ "tools.offer('web/search')\ntools.offer_dynamic('web')",
+ "tools.offer_dynamic('web')\ntools.offer('web/search')",
+ ] {
+ let vm = lua_over(offer_set());
+ vm.exec(source);
+ assert_eq!(scoped(&vm), ["web_search"], "{source}");
+ assert_eq!(
+ dynamic(&vm),
+ ["web/fetch"],
+ "static wins in either order: {source}"
+ );
+ }
+ let vm = lua_over(offer_set());
+ vm.exec(
+ "tools.offer_dynamic('gh/search')\n\
+ tools.offer_dynamic({ 'gh', 'gh/search' })\n\
+ tools.offer_dynamic(tools.packs.get('adhoc'))\n\
+ tools.adhoc({ name = 'late', description = 'Late' }, function() end)",
+ );
+ assert_eq!(
+ dynamic(&vm),
+ ["gh/search", "gh/issues.list", "adhoc/late"],
+ "each tool once, in offer order, adhoc tools defined before the render included"
+ );
+ assert!(
+ scoped(&vm).is_empty(),
+ "dynamic offers never reach the static list"
+ );
+}
+
+#[test]
+fn a_catalog_tool_a_static_adhoc_tool_shadows_stays_out_of_the_dynamic_list() {
+ let vm = lua_over(offer_set());
+ vm.exec(
+ "tools.offer(tools.adhoc({ name = 'web_search', description = 'Mine' }, function() end))\n\
+ tools.offer_dynamic('web')",
+ );
+ assert_eq!(scoped(&vm), ["web_search"]);
+ assert_eq!(
+ dynamic(&vm),
+ ["web/fetch"],
+ "a tool whose wire name the static list holds is skipped"
+ );
+}
+
+#[test]
+fn dynamic_offers_leave_the_static_bindings_unchanged() {
+ let plain = lua_over(offer_set());
+ plain.exec("tools.offer({ 'web/search', 'gh' })");
+ let with_dynamic = lua_over(offer_set());
+ with_dynamic.exec(
+ "tools.offer_dynamic('web')\n\
+ tools.offer({ 'web/search', 'gh' })\n\
+ tools.offer_dynamic(tools.packs)",
+ );
+ let bindings = |vm: &crate::SectionVm| {
+ let (set, runtime) = vm.tool_bag_handles();
+ crate::current_tool_bindings(&set, &runtime, vm.adhoc_tools()).expect("the scope resolves")
+ };
+ assert_eq!(bindings(&plain), bindings(&with_dynamic));
+}
+
+#[test]
+fn the_same_offers_give_the_same_lists_in_every_vm() {
+ let source = "tools.adhoc({ name = 'b', description = 'B' }, function() end)\n\
+ tools.adhoc({ name = 'a', description = 'A' }, function() end)\n\
+ tools.offer(tools.packs)\n\
+ tools.offer_dynamic(tools.packs.extras())";
+ let lists: Vec<(Vec, Vec)> = (0..4)
+ .map(|_| {
+ let vm = lua_over(offer_set());
+ vm.exec(source);
+ (scoped(&vm), dynamic(&vm))
+ })
+ .collect();
+ assert!(
+ lists.windows(2).all(|pair| pair[0] == pair[1]),
+ "nothing is hash-ordered: {lists:?}"
+ );
+ assert_eq!(lists[0].0[..2], ["a", "b"]);
+}
diff --git a/crates/runvil-internal/lua/src/tools/tests.rs b/crates/runvil-internal/lua/src/tools/tests.rs
index 456cb4de7..64351e02f 100644
--- a/crates/runvil-internal/lua/src/tools/tests.rs
+++ b/crates/runvil-internal/lua/src/tools/tests.rs
@@ -1,17 +1,26 @@
-//! Tests for the `tools` namespace installers, alias decoding, and the local params schema.
+//! Tests for the `tools` namespace installers, tool-name decoding, and the
+//! short-form `parameters` schema.
use std::collections::BTreeMap;
-use mlua::{Lua, Value, Variadic};
+use mlua::{Lua, Value};
use serde_json::json;
-use super::decode::{collect_offer_entries, local_params_schema, tool_name};
+use super::decode::{adhoc_params_schema, model_tool_name, tool_name};
use super::userdata::LuaToolHandle;
use crate::test_vm::{TestVm, echo_tool, lua_over, tool_at};
use crate::{ToolBinding, ToolSet};
+#[path = "tests-adhoc.rs"]
+mod adhoc;
+#[path = "tests-offer-limits.rs"]
+mod offer_limits;
#[path = "tests-offering.rs"]
mod offering;
+#[path = "tests-parameters.rs"]
+mod parameters;
+#[path = "tests-render.rs"]
+mod render;
/// A userdata that is not a Tool object, for the foreign-userdata rejection.
struct Foreign;
@@ -22,16 +31,53 @@ fn echo_handle() -> LuaToolHandle {
LuaToolHandle::from_binding(&ToolBinding::from_info("tools_echo", &echo_tool()))
}
+fn string(lua: &Lua, text: &str) -> Value {
+ Value::String(
+ lua.create_string(text)
+ .expect("a fresh VM creates a short string"),
+ )
+}
+
#[test]
-fn tool_name_accepts_a_bare_string() {
+fn tool_name_accepts_an_id_and_refuses_a_string_without_a_slash() {
let lua = Lua::new();
- let value = lua
- .create_string("tools/echo")
- .expect("a fresh VM creates a short string");
assert_eq!(
- tool_name(&Value::String(value)).expect("a string decodes"),
+ tool_name(&string(&lua, "tools/echo")).expect("an id decodes"),
"tools/echo"
);
+ let error = tool_name(&string(&lua, "grab")).expect_err("a bare name is not an id");
+ assert!(
+ error
+ .to_string()
+ .contains("tools.call: \"grab\" is not a tool id"),
+ "the refusal names the string: {error}"
+ );
+}
+
+#[test]
+fn a_model_issued_name_is_read_verbatim() {
+ let lua = Lua::new();
+ assert_eq!(
+ model_tool_name(&string(&lua, "web_search")).expect("a wire name decodes"),
+ "web_search",
+ "a model names a tool by the wire name it was sent"
+ );
+}
+
+#[test]
+fn a_model_issued_call_refuses_a_tool_object() {
+ let lua = Lua::new();
+ let userdata = lua
+ .create_userdata(echo_handle())
+ .expect("a fresh VM creates a tool object");
+ let error = model_tool_name(&Value::UserData(userdata))
+ .expect_err("a model-issued call names a wire name, not an object");
+ assert!(
+ error
+ .to_string()
+ .contains("a model-issued tool call names a tool by its wire name, got userdata"),
+ "the refusal names the wire-name form: {error}"
+ );
}
#[test]
@@ -43,7 +89,7 @@ fn tool_name_reads_the_id_off_a_tool_object() {
assert_eq!(
tool_name(&Value::UserData(userdata)).expect("a tool object decodes"),
"tools/echo",
- "a tool object stands for its canonical id, not its wire name"
+ "a tool object stands for its id, not its wire name"
);
}
@@ -54,7 +100,7 @@ fn tool_name_rejects_tables_other_types_and_other_userdata() {
assert!(
number
.to_string()
- .contains("tools.call takes a tool id, a local alias, or a tool object, got integer"),
+ .contains("tools.call takes a tool id or a tool object, got integer"),
"the rejection names the accepted forms: {number}"
);
let record = lua
@@ -75,59 +121,19 @@ fn tool_name_rejects_tables_other_types_and_other_userdata() {
assert!(
other
.to_string()
- .contains("tools.call takes a tool id, a local alias, or a tool object, got userdata"),
+ .contains("tools.call takes a tool id or a tool object, got userdata"),
"a foreign userdata gets the same rejection: {other}"
);
}
#[test]
-fn tools_offer_entries_accept_strings_tool_objects_and_arrays() {
- let lua = Lua::new();
- let tool = lua
- .create_userdata(echo_handle())
- .expect("a fresh VM creates a tool object");
- let entries = collect_offer_entries(
- "tools.offer",
- Variadic::from_iter([Value::String(
- lua.create_string("web/search")
- .expect("a fresh VM creates a short string"),
- )]),
- )
- .expect("an id decodes");
- assert_eq!(entries, ["web/search"]);
- let entries = collect_offer_entries(
- "tools.offer",
- Variadic::from_iter([Value::UserData(tool.clone())]),
- )
- .expect("a tool object decodes");
- assert_eq!(entries, ["tools/echo"]);
-
- let array = lua
- .create_sequence_from(vec![Value::UserData(tool)])
- .expect("a fresh VM creates the offer array");
- array
- .raw_push(Value::String(
- lua.create_string("web/fetch")
- .expect("a fresh VM creates a short string"),
- ))
- .expect("a fresh array takes a pushed id");
- let entries = collect_offer_entries("tools.offer", Variadic::from_iter([Value::Table(array)]))
- .expect("the array form decodes");
- assert_eq!(
- entries,
- ["tools/echo", "web/fetch"],
- "tool objects and ids mix in the array form"
- );
-}
-
-#[test]
-fn local_params_schema_builds_object_schema_with_required_fields() {
+fn adhoc_params_schema_builds_object_schema_with_required_fields() {
let lua = Lua::new();
let params = lua
.load("{ query = 'string', limit = { 'integer', 'maximum hits' } }")
.eval::()
.expect("params table evaluates");
- let schema = local_params_schema(¶ms).expect("the schema builds");
+ let schema = adhoc_params_schema(¶ms).expect("the schema builds");
assert_eq!(
schema["properties"],
json!({
@@ -144,7 +150,7 @@ fn local_params_schema_builds_object_schema_with_required_fields() {
}
#[test]
-fn local_params_schema_sorts_required_so_the_schema_text_is_deterministic() {
+fn adhoc_params_schema_sorts_required_so_the_schema_text_is_deterministic() {
// `required` is the one Rust-side `table.pairs` walk whose output is an
// ordered array rather than a table or map, so it must impose an order
// itself: left as the walk produced it, two VMs emit different schema
@@ -158,7 +164,7 @@ fn local_params_schema_sorts_required_so_the_schema_text_is_deterministic() {
)
.eval::()
.expect("params table evaluates");
- let schema = local_params_schema(¶ms).expect("the schema builds");
+ let schema = adhoc_params_schema(¶ms).expect("the schema builds");
assert_eq!(
schema["required"],
json!([
@@ -169,32 +175,36 @@ fn local_params_schema_sorts_required_so_the_schema_text_is_deterministic() {
}
#[test]
-fn local_params_schema_rejects_an_unsupported_type() {
+fn adhoc_params_schema_rejects_an_unsupported_type_under_the_adhoc_prefix() {
let lua = Lua::new();
let params = lua
.load("{ payload = 'table' }")
.eval::()
.expect("params table evaluates");
- let error = local_params_schema(¶ms).expect_err("an unsupported type fails");
+ let error = adhoc_params_schema(¶ms).expect_err("an unsupported type fails");
assert!(
- error.to_string().contains("unsupported type \"table\""),
+ error
+ .to_string()
+ .contains("tools.adhoc: param \"payload\" has unsupported type \"table\""),
"the rejection names the bad type: {error}"
);
}
#[test]
-fn the_tools_namespace_exposes_scoping_without_bind_or_call() {
+fn the_tools_namespace_exposes_its_verbs_without_bind_or_call() {
// `call` is absent here on purpose: it suspends, so the coroutine shim
// prelude installs it - this table exposes exactly the non-suspending
// operations. `bind` is absent too.
let vm = TestVm::new().build();
- let (has_offer, has_offer_local, call_is_nil, bind_is_nil): (bool, bool, bool, bool) = vm.eval(
+ let shapes: (bool, bool, bool, bool, bool, bool) = vm.eval(
"return type(tools.offer) == 'function', \
- type(tools.offer_local) == 'function', \
+ type(tools.offer_dynamic) == 'function', \
+ type(tools.adhoc) == 'function', \
+ type(tools.packs) == 'table', \
tools.call == nil, \
tools.bind == nil",
);
- assert!(has_offer && has_offer_local && call_is_nil && bind_is_nil);
+ assert_eq!(shapes, (true, true, true, true, true, true));
}
#[test]
@@ -219,7 +229,7 @@ fn tool_call_counts_seed_by_id_and_explain_an_unseeded_key() {
],
));
let counts = vm
- .install_tool_call_counts(&[echo])
+ .install_tool_call_counts(&[echo.id().clone()])
.expect("the counts install");
assert_eq!(
counts
@@ -234,6 +244,7 @@ fn tool_call_counts_seed_by_id_and_explain_an_unseeded_key() {
None,
"counts key a catalog tool by its id, never its wire name"
);
+ vm.exec("tools.adhoc({ name = 'grab', description = 'Grab a value' }, function() end)");
let read = |key: &str| -> String {
vm.eval(&format!(
"local ok, err = pcall(function() return tools.calls[{key:?}] end); return tostring(err)"
@@ -248,7 +259,17 @@ fn tool_call_counts_seed_by_id_and_explain_an_unseeded_key() {
),
"an offered id that was never seeded says so: {offered}"
);
- for key in ["ghost", "tools_echo"] {
+ let adhoc = read("adhoc/grab");
+ assert!(
+ adhoc.contains(
+ "tools.calls: \"adhoc/grab\" has no seeded count; seeded names: [\"tools/echo\"] \
+ (an adhoc tool that was neither offered in this section nor called with \
+ tools.call)"
+ ),
+ "a defined adhoc tool's id that was never seeded says so, even when defined \
+ after the counts install: {adhoc}"
+ );
+ for key in ["ghost", "tools_echo", "grab"] {
let error = read(key);
assert!(
error.contains(&format!("tools.calls: {key:?} has no seeded count"))
diff --git a/crates/runvil-internal/lua/src/tools/userdata.rs b/crates/runvil-internal/lua/src/tools/userdata.rs
index c2a5108f3..fa662436f 100644
--- a/crates/runvil-internal/lua/src/tools/userdata.rs
+++ b/crates/runvil-internal/lua/src/tools/userdata.rs
@@ -1,35 +1,40 @@
-//! The tool object: one catalog tool as Lua sees it.
+//! The tool object: one tool as Lua sees it.
//!
-//! Presentation only: the userdata exposes an offered tool's `id`, its
-//! catalog `description`, and its `pack`, the Pack object
-//! `packs.get` returns, and stands for its id wherever `tools.offer` and
-//! `tools.call` take a tool. The object is frozen and methodless, so
-//! `description` is always the catalog text. Unlike a model handle, which
-//! carries `infer` and `loop`, it is invoked only through
-//! `tools.call(tool, arguments)`.
+//! Presentation only: the userdata exposes a tool's `id`, its
+//! `description`, its `parameters` schema, and its `pack`, the Pack
+//! object `tools.packs.get` returns, and stands for its id wherever
+//! `tools.offer` and `tools.call` take a tool. The object is frozen and
+//! methodless, so `description` is always the text the Pack or the
+//! `tools.adhoc` attrs declared, and each `parameters` read is a fresh
+//! table of the schema as declared. Neither is ever in the untrusted
+//! envelope. Unlike a model handle, which carries `infer` and `loop`, it
+//! is invoked only through `tools.call(tool, arguments)`.
-use mlua::{MetaMethod, UserData, UserDataFields, UserDataMethods, Value};
+use mlua::{LuaSerdeExt, MetaMethod, UserData, UserDataFields, UserDataMethods, Value};
use runvil_types::tools::ToolId;
+use serde_json::Value as Json;
use crate::handles::ToolBinding;
use crate::packs::pack_object;
-/// One catalog tool as Lua sees it: `id`, `description`, and `pack`,
-/// all read-only.
+/// One tool as Lua sees it: `id`, `description`, `parameters`, and
+/// `pack`, all read-only.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct LuaToolHandle {
id: ToolId,
description: String,
+ parameters: Json,
}
impl LuaToolHandle {
- /// Builds the object for an offered tool from its binding: the id and
- /// the catalog description, never the binding's override.
+ /// Builds the object for a tool from its binding: the id, the
+ /// declared description, and the parameter schema.
#[must_use]
pub(crate) fn from_binding(binding: &ToolBinding) -> Self {
Self {
id: binding.id().clone(),
description: binding.description().to_owned(),
+ parameters: binding.schema().clone(),
}
}
@@ -44,6 +49,10 @@ impl UserData for LuaToolHandle {
fn add_fields>(fields: &mut F) {
fields.add_field_method_get("id", |_, this| Ok(this.id.to_string()));
fields.add_field_method_get("description", |_, this| Ok(this.description.clone()));
+ // The conversion `json.decode` makes: lists carry the array
+ // marker, so `json.encode` gives back `[]`, and nulls read
+ // `json.null`.
+ fields.add_field_method_get("parameters", |lua, this| lua.to_value(&this.parameters));
fields.add_field_method_get("pack", |lua, this| {
pack_object(lua, &this.id.pack().to_string())
});
diff --git a/crates/runvil-internal/lua/src/vm.rs b/crates/runvil-internal/lua/src/vm.rs
index ad657c32f..f5aba89e9 100644
--- a/crates/runvil-internal/lua/src/vm.rs
+++ b/crates/runvil-internal/lua/src/vm.rs
@@ -1,19 +1,20 @@
//! The per-section Lua VM: its construction, the typestate that orders
//! Engine injection before every later step, the section's one
-//! `messages` list it creates, and the local tools it registers.
+//! `messages` list it creates, and the adhoc tools it defines.
//! Injection is in `inject`, the later installs in `install`, block
-//! coroutines in `run`, and state reads in `state`.
+//! coroutines in `run`, state reads in `state`, and the adhoc tools in
+//! `adhoc`.
//!
-//! A local tool, registered with `tools.offer_local` before the section's
-//! first loop round, runs inside the calling block's coroutine, never as
-//! an Engine function. The VM keeps only each
-//! tool's alias and schema; the handler sits in the VM's handler table. A
-//! call takes two yields: the shim's `tool_call`, which the scheduler
-//! answers with the handler itself, and the shim's `local_tool_done`
-//! after the handler ran, which carries its result for the scheduler to
-//! report. Every suspending call the handler makes in between is an
-//! ordinary yield of the same coroutine.
-
+//! An adhoc tool, defined with `tools.adhoc`, runs inside the calling
+//! block's coroutine, never as an Engine function. The VM keeps each
+//! tool's binding; the handler sits in the VM's handler table. A call
+//! takes two yields: the shim's `tool_call`, which the scheduler answers
+//! with the handler itself, and the shim's `adhoc_tool_done` after the
+//! handler ran, which carries its result for the scheduler to report.
+//! Every suspending call the handler makes in between is an ordinary
+//! yield of the same coroutine.
+
+mod adhoc;
mod inject;
mod install;
mod run;
@@ -23,7 +24,6 @@ use std::sync::atomic::{AtomicBool, AtomicU32, AtomicUsize, Ordering};
use std::sync::{Arc, Mutex};
use mlua::{Lua, LuaOptions, StdLib};
-use runvil_model_client::client::ToolSchema;
use runvil_model_client::model::ModelSet;
use runvil_types::emitter::Emitter;
use runvil_types::event::lifecycle;
@@ -31,7 +31,6 @@ use runvil_types::untrusted::GuardNonce;
use runvil_vfs::Access;
use serde_json::Value as Json;
-use crate::alias::Alias;
use crate::engine_globals::{LUA_LOG_CHARACTER_LIMIT, install_untrusted};
use crate::error::{Error, Result};
use crate::handles::ToolSet;
@@ -43,10 +42,11 @@ use crate::program::LuaProgram;
use crate::scope::ToolRuntime;
use crate::walk_budget::HeapCeiling;
+pub use adhoc::AdhocTools;
pub use inject::InjectFailure;
pub use run::CoroStep;
pub(crate) use run::scalar_return;
-pub use state::{current_tool_bindings, resolve_model_binding};
+pub use state::{current_dynamic_tools, current_tool_bindings, resolve_model_binding};
/// Default per-VM Lua heap ceiling, matching the executor's `RunLimits`.
pub(crate) const DEFAULT_LUA_MEMORY_BYTES: usize = 64 * 1024 * 1024;
@@ -128,9 +128,9 @@ pub struct SectionVm {
model_runtime: Arc>,
/// Set by Lua `jump` before it aborts the current chunk.
jump_slot: Arc