feat: add console observation command

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
BB-fat
2026-07-07 11:08:12 +08:00
co-authored by Cursor
parent ce29ddaa53
commit 7f5093d97a
23 changed files with 1538 additions and 44 deletions
+131
View File
@@ -0,0 +1,131 @@
//! `bsk console` — read buffered page console/log/exception messages.
use std::path::PathBuf;
use anyhow::Context;
use bsk_protocol::Method;
use bsk_protocol::tools::{ConsoleEntry, ConsoleParams, ConsoleResult};
use clap::Args;
use crate::cli::TOOL_IPC_TIMEOUT;
use crate::cli::ensure_daemon::ensure_daemon;
use crate::cli::error::{CliError, Format};
#[derive(Debug, Clone, Args)]
pub struct ConsoleArgs {
/// Session id (must be active).
#[arg(long)]
pub session: String,
/// Target tab. Defaults to the Agent Window's active tab.
#[arg(long = "tab-id")]
pub tab_id: Option<i64>,
/// Return entries with sequence greater than this cursor.
#[arg(long)]
pub since: Option<u64>,
/// Maximum number of entries to return. Defaults to 50; extension caps at 200.
#[arg(long, value_parser = clap::value_parser!(u32).range(1..))]
pub limit: Option<u32>,
/// Maximum characters per entry text. Defaults to 1000; extension caps at 4096.
#[arg(long = "max-text-chars", value_parser = clap::value_parser!(u32).range(1..))]
pub max_text_chars: Option<u32>,
/// Include structured stack frames in JSON/human output.
#[arg(long = "include-stack", default_value_t = false)]
pub include_stack: bool,
}
pub fn dispatch(args: ConsoleArgs, format: Format) -> Result<(), CliError> {
let info = ensure_daemon().context("ensure daemon is running")?;
run(info.sock_path, args, format)
}
fn run(sock: PathBuf, args: ConsoleArgs, format: Format) -> Result<(), CliError> {
let params = ConsoleParams {
session_id: args.session,
tab_id: args.tab_id,
since: args.since,
limit: args.limit,
max_text_chars: args.max_text_chars,
include_stack: args.include_stack.then_some(true),
};
let reply: ConsoleResult = call(sock, params)?;
render(&reply, format)
}
fn call(sock: PathBuf, params: ConsoleParams) -> Result<ConsoleResult, CliError> {
crate::cli::business_rpc::call::<ConsoleParams, ConsoleResult>(
sock,
"console",
Method::ToolConsole,
Some(params),
TOOL_IPC_TIMEOUT,
)
}
fn render(reply: &ConsoleResult, format: Format) -> Result<(), CliError> {
match format {
Format::Json => {
let json = serde_json::to_string_pretty(reply)
.map_err(|e| CliError::Local(anyhow::anyhow!(e)))?;
println!("{json}");
}
Format::Human => {
if reply.entries.is_empty() {
println!("(no console messages captured)");
} else {
for entry in &reply.entries {
println!("{}", render_entry(entry));
for frame in &entry.stack_trace {
let loc = render_location(frame.url.as_deref(), frame.line, frame.column);
let name = frame.function_name.as_deref().unwrap_or("<anonymous>");
println!(" at {name} {loc}");
}
}
}
if reply.truncated {
eprintln!(
"warning: console output truncated (next_since={}). Use --since / --limit / --max-text-chars to request a different slice.",
reply.next_since
);
}
}
}
Ok(())
}
fn render_entry(entry: &ConsoleEntry) -> String {
let loc = render_location(entry.url.as_deref(), entry.line, entry.column);
if loc.is_empty() {
format!(
"#{} {} {} {}",
entry.sequence,
entry.level,
entry.kind.as_str(),
entry.text
)
} else {
format!(
"#{} {} {} {} {}",
entry.sequence,
entry.level,
entry.kind.as_str(),
loc,
entry.text
)
}
}
fn render_location(url: Option<&str>, line: Option<i64>, column: Option<i64>) -> String {
let Some(url) = url else {
return String::new();
};
match (line, column) {
(Some(line), Some(column)) => format!("{url}:{line}:{column}"),
(Some(line), None) => format!("{url}:{line}"),
_ => url.to_string(),
}
}
+5
View File
@@ -5,6 +5,7 @@ use std::time::Duration;
pub mod browser_wait;
pub mod browsers;
pub mod business_rpc;
pub mod console;
pub mod daemon;
pub mod dialogs;
pub mod doctor;
@@ -27,6 +28,7 @@ pub mod waits;
use clap::{Args, Parser, Subcommand};
use crate::cli::console::ConsoleArgs;
use crate::cli::daemon::DaemonCmd;
use crate::cli::evaluate::EvaluateArgs;
use crate::cli::get_html::GetHtmlArgs;
@@ -110,6 +112,9 @@ pub enum Command {
/// Produce an indented aria-snapshot with @eN refs.
Snapshot(SnapshotArgs),
/// Read buffered console/log/exception messages.
Console(ConsoleArgs),
/// Dump raw HTML for a tab or a snapshot ref.
#[command(name = "get-html")]
GetHtml(GetHtmlArgs),
+1
View File
@@ -228,6 +228,7 @@ pub fn full_handler(status: DaemonStatus, state: Arc<DaemonState>) -> RpcHandler
| Method::ToolTabBorrow
| Method::ToolTabReturn
| Method::ToolScreenshot
| Method::ToolConsole
| Method::ToolSnapshot
| Method::ToolGetHtml
| Method::ToolNavigate
+1
View File
@@ -77,6 +77,7 @@ fn dispatch(cli: Cli, format: Format) -> Result<(), CliError> {
Command::Tab(cmd) => cli::tab::dispatch(cmd, format),
Command::Screenshot(args) => cli::screenshot::dispatch(args, format),
Command::Snapshot(args) => cli::snapshot::dispatch(args, format),
Command::Console(args) => cli::console::dispatch(args, format),
Command::GetHtml(args) => cli::get_html::dispatch(args, format),
Command::Navigate(args) => cli::navigate::dispatch_navigate_command(args, format),
Command::NavigateBack(args) => cli::navigate::dispatch_navigate_back(args, format),
+37
View File
@@ -67,6 +67,43 @@ fn parses_top_level_status_and_doctor() {
assert!(matches!(cli.command, Command::Doctor));
}
#[test]
fn parses_console_command_with_context_safety_flags() {
let cli = parse(&[
"bsk",
"console",
"--session",
"s1",
"--tab-id",
"9",
"--since",
"12",
"--limit",
"75",
"--max-text-chars",
"2048",
"--include-stack",
]);
let Command::Console(args) = cli.command else {
panic!("expected console command");
};
assert_eq!(args.session, "s1");
assert_eq!(args.tab_id, Some(9));
assert_eq!(args.since, Some(12));
assert_eq!(args.limit, Some(75));
assert_eq!(args.max_text_chars, Some(2048));
assert!(args.include_stack);
}
#[test]
fn rejects_zero_console_bounds() {
assert!(Cli::try_parse_from(["bsk", "console", "--session", "s1", "--limit", "0"]).is_err());
assert!(
Cli::try_parse_from(["bsk", "console", "--session", "s1", "--max-text-chars", "0"])
.is_err()
);
}
#[test]
fn parses_install_skill_subcommand() {
let cli = parse(&["bsk", "install-skill", "--list"]);
+26 -4
View File
@@ -428,8 +428,8 @@ async fn read_only_tool_passes_through_without_consuming_interrupt_marker() {
let (ws_sink, ws_stream) = ws.split();
let ws_sink = Arc::new(tokio::sync::Mutex::new(ws_sink));
// Fake extension: replies to session_start AND to snapshot
// (snapshot must succeed transparently). Records click count
// Fake extension: replies to session_start, console, and snapshot
// (read-only tools must succeed transparently). Records click count
// — must remain 0 because the daemon should reject the click
// without forwarding.
let ws_sink_for_responder = Arc::clone(&ws_sink);
@@ -454,6 +454,12 @@ async fn read_only_tool_passes_through_without_consuming_interrupt_marker() {
})
.unwrap(),
),
Method::ToolConsole => ResponseBody::Ok(json!({
"tab_id": 7,
"entries": [],
"next_since": 0,
"truncated": false
})),
Method::ToolSnapshot => ResponseBody::Ok(json!({"ok": true})),
Method::ToolClick => {
observed_click_count_clone
@@ -511,8 +517,24 @@ async fn read_only_tool_passes_through_without_consuming_interrupt_marker() {
let state = handle.state();
wait_for_session_interrupt_pending(&state, &start.session_id).await;
// Read-only snapshot must succeed AND must not consume the
// marker.
// Read-only console must succeed AND must not consume the marker.
let console_outcome = ipc
.call::<_, serde_json::Value>(
"console-after-interrupt",
Method::ToolConsole,
Some(json!({"session_id": start.session_id.clone()})),
Duration::from_secs(3),
)
.await
.unwrap();
assert!(
console_outcome.is_ok(),
"read-only tool.console must pass through transparently (got {:?})",
console_outcome
);
// Existing read-only snapshot must still succeed after console,
// proving console did not consume the marker.
let snapshot_outcome = ipc
.call::<_, serde_json::Value>(
"snap-after-interrupt",
+60 -3
View File
@@ -10,9 +10,9 @@ use bsk::daemon::{self, DaemonConfig};
use bsk::ipc_client::IpcClient;
use bsk_protocol::system::{HandshakeParams, HandshakeResult};
use bsk_protocol::tools::{
GetHtmlParams, GetHtmlResult, ScreenshotParams, ScreenshotResult, SessionStartParams,
SessionStartResult, SnapshotParams, SnapshotResult, TabInfo, TabListParams, TabListResult,
TabScope,
ConsoleEntry, ConsoleEntryKind, ConsoleParams, ConsoleResult, GetHtmlParams, GetHtmlResult,
ScreenshotParams, ScreenshotResult, SessionStartParams, SessionStartResult, SnapshotParams,
SnapshotResult, TabInfo, TabListParams, TabListResult, TabScope,
};
use bsk_protocol::{
BrowserPeerInfo, ErrorCode, Frame, Method, RequestFrame, ResponseBody, ResponseFrame, RpcError,
@@ -311,6 +311,63 @@ async fn screenshot_forwards_ref_to_extension() {
handle.shutdown().await;
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn console_returns_buffered_entries() {
let (handle, sock) = spawn_daemon().await;
let mut ws = connect_ext(handle.ws_addr()).await;
let _ = do_handshake(&mut ws).await;
run_extension(ws, |req| {
assert_eq!(req.method, Method::ToolConsole);
let params: ConsoleParams = serde_json::from_value(req.params.clone().unwrap()).unwrap();
assert_eq!(params.tab_id, Some(7));
assert_eq!(params.since, Some(3));
assert_eq!(params.limit, Some(50));
assert_eq!(params.max_text_chars, Some(1000));
assert_eq!(params.include_stack, Some(false));
ResponseBody::Ok(
serde_json::to_value(ConsoleResult {
tab_id: 7,
entries: vec![ConsoleEntry {
sequence: 4,
kind: ConsoleEntryKind::Console,
level: "warn".into(),
text: "deprecated API".into(),
url: Some("https://example.test/app.js".into()),
line: Some(10),
column: Some(2),
timestamp: None,
stack_trace: vec![],
truncated: false,
}],
next_since: 4,
truncated: false,
})
.unwrap(),
)
});
let session_id = ipc_session_start(&sock).await;
let result: ConsoleResult = ipc_tool_call(
&sock,
Method::ToolConsole,
ConsoleParams {
session_id,
tab_id: Some(7),
since: Some(3),
limit: Some(50),
max_text_chars: Some(1000),
include_stack: Some(false),
},
)
.await
.expect("console ok");
assert_eq!(result.tab_id, 7);
assert_eq!(result.next_since, 4);
assert_eq!(result.entries[0].text, "deprecated API");
handle.shutdown().await;
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn snapshot_returns_text_and_ref_count() {
let (handle, sock) = spawn_daemon().await;
@@ -0,0 +1,105 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "ConsoleEntry",
"type": "object",
"required": [
"kind",
"level",
"sequence",
"text"
],
"properties": {
"column": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"kind": {
"$ref": "#/definitions/ConsoleEntryKind"
},
"level": {
"type": "string"
},
"line": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"sequence": {
"type": "integer",
"format": "uint64",
"minimum": 0.0
},
"stack_trace": {
"type": "array",
"items": {
"$ref": "#/definitions/ConsoleStackFrame"
}
},
"text": {
"type": "string"
},
"timestamp": {
"type": [
"number",
"null"
],
"format": "double"
},
"truncated": {
"default": false,
"type": "boolean"
},
"url": {
"type": [
"string",
"null"
]
}
},
"definitions": {
"ConsoleEntryKind": {
"type": "string",
"enum": [
"console",
"exception",
"log"
]
},
"ConsoleStackFrame": {
"type": "object",
"properties": {
"column": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"function_name": {
"type": [
"string",
"null"
]
},
"line": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"url": {
"type": [
"string",
"null"
]
}
}
}
}
}
@@ -0,0 +1,55 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "ConsoleParams",
"type": "object",
"required": [
"session_id"
],
"properties": {
"include_stack": {
"description": "Include structured stack frames. Defaults to false.",
"type": [
"boolean",
"null"
]
},
"limit": {
"description": "Maximum number of entries to return. Extension applies safe defaults and caps.",
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 1.0
},
"max_text_chars": {
"description": "Maximum characters returned per entry text. Extension applies safe defaults and caps.",
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 1.0
},
"session_id": {
"type": "string"
},
"since": {
"description": "Return entries with sequence strictly greater than this cursor.",
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0.0
},
"tab_id": {
"description": "Optional target tab. Defaults to the Agent Window's currently active tab.",
"type": [
"integer",
"null"
],
"format": "int64"
}
}
}
@@ -0,0 +1,133 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "ConsoleResult",
"type": "object",
"required": [
"next_since",
"tab_id"
],
"properties": {
"entries": {
"type": "array",
"items": {
"$ref": "#/definitions/ConsoleEntry"
}
},
"next_since": {
"type": "integer",
"format": "uint64",
"minimum": 0.0
},
"tab_id": {
"type": "integer",
"format": "int64"
},
"truncated": {
"default": false,
"type": "boolean"
}
},
"definitions": {
"ConsoleEntry": {
"type": "object",
"required": [
"kind",
"level",
"sequence",
"text"
],
"properties": {
"column": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"kind": {
"$ref": "#/definitions/ConsoleEntryKind"
},
"level": {
"type": "string"
},
"line": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"sequence": {
"type": "integer",
"format": "uint64",
"minimum": 0.0
},
"stack_trace": {
"type": "array",
"items": {
"$ref": "#/definitions/ConsoleStackFrame"
}
},
"text": {
"type": "string"
},
"timestamp": {
"type": [
"number",
"null"
],
"format": "double"
},
"truncated": {
"default": false,
"type": "boolean"
},
"url": {
"type": [
"string",
"null"
]
}
}
},
"ConsoleEntryKind": {
"type": "string",
"enum": [
"console",
"exception",
"log"
]
},
"ConsoleStackFrame": {
"type": "object",
"properties": {
"column": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"function_name": {
"type": [
"string",
"null"
]
},
"line": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"url": {
"type": [
"string",
"null"
]
}
}
}
}
}
@@ -0,0 +1,33 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "ConsoleStackFrame",
"type": "object",
"properties": {
"column": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"function_name": {
"type": [
"string",
"null"
]
},
"line": {
"type": [
"integer",
"null"
],
"format": "int64"
},
"url": {
"type": [
"string",
"null"
]
}
}
}
@@ -82,6 +82,10 @@ fn main() {
dump!(GetHtmlResult, "tool_get_html_result");
dump!(ScreenshotParams, "tool_screenshot_params");
dump!(ScreenshotResult, "tool_screenshot_result");
dump!(ConsoleParams, "tool_console_params");
dump!(ConsoleResult, "tool_console_result");
dump!(ConsoleEntry, "tool_console_entry");
dump!(ConsoleStackFrame, "tool_console_stack_frame");
dump!(EvaluateParams, "tool_evaluate_params");
dump!(EvaluateResult, "tool_evaluate_result");
+11
View File
@@ -62,6 +62,8 @@ pub enum Method {
ToolGetHtml,
#[serde(rename = "tool.screenshot")]
ToolScreenshot,
#[serde(rename = "tool.console")]
ToolConsole,
#[serde(rename = "tool.evaluate")]
ToolEvaluate,
#[serde(rename = "tool.wait_for_navigation")]
@@ -124,6 +126,7 @@ impl Method {
| Method::ToolSnapshot
| Method::ToolGetHtml
| Method::ToolScreenshot
| Method::ToolConsole
| Method::ToolWaitForNavigation
| Method::ToolWaitMs
| Method::ToolRequestHelp => false,
@@ -159,6 +162,13 @@ mod tests {
assert_eq!(serde_json::to_value(method).unwrap(), json!("cancel"));
}
#[test]
fn console_method_round_trips() {
let method: Method = serde_json::from_value(json!("tool.console")).unwrap();
assert_eq!(method, Method::ToolConsole);
assert_eq!(serde_json::to_value(method).unwrap(), json!("tool.console"));
}
#[test]
fn cancel_params_and_result_round_trip() {
let params: CancelParams = serde_json::from_value(json!({ "rpc_id": "wait-1" })).unwrap();
@@ -176,6 +186,7 @@ mod tests {
assert!(!Method::ToolSnapshot.is_mutating());
assert!(!Method::ToolGetHtml.is_mutating());
assert!(!Method::ToolScreenshot.is_mutating());
assert!(!Method::ToolConsole.is_mutating());
assert!(!Method::ToolWaitForNavigation.is_mutating());
assert!(!Method::ToolWaitMs.is_mutating());
}
+147
View File
@@ -0,0 +1,147 @@
//! `tool.console` — read buffered console/log/exception messages.
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct ConsoleParams {
pub session_id: String,
/// Optional target tab. Defaults to the Agent Window's currently active tab.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub tab_id: Option<i64>,
/// Return entries with sequence strictly greater than this cursor.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub since: Option<u64>,
/// Maximum number of entries to return. Extension applies safe defaults and caps.
#[serde(default, skip_serializing_if = "Option::is_none")]
#[schemars(range(min = 1))]
pub limit: Option<u32>,
/// Maximum characters returned per entry text. Extension applies safe defaults and caps.
#[serde(default, skip_serializing_if = "Option::is_none")]
#[schemars(range(min = 1))]
pub max_text_chars: Option<u32>,
/// Include structured stack frames. Defaults to false.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub include_stack: Option<bool>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum ConsoleEntryKind {
Console,
Exception,
Log,
}
impl ConsoleEntryKind {
pub fn as_str(self) -> &'static str {
match self {
Self::Console => "console",
Self::Exception => "exception",
Self::Log => "log",
}
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct ConsoleStackFrame {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub function_name: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub url: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub line: Option<i64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub column: Option<i64>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct ConsoleEntry {
pub sequence: u64,
pub kind: ConsoleEntryKind,
pub level: String,
pub text: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub url: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub line: Option<i64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub column: Option<i64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub timestamp: Option<f64>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub stack_trace: Vec<ConsoleStackFrame>,
#[serde(default)]
pub truncated: bool,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct ConsoleResult {
pub tab_id: i64,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub entries: Vec<ConsoleEntry>,
pub next_since: u64,
#[serde(default)]
pub truncated: bool,
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
#[test]
fn console_params_omit_optional_fields() {
let params = ConsoleParams {
session_id: "aa11".into(),
tab_id: None,
since: None,
limit: None,
max_text_chars: None,
include_stack: None,
};
let value = serde_json::to_value(&params).unwrap();
assert_eq!(value["session_id"], "aa11");
assert!(value.get("tab_id").is_none());
assert!(value.get("since").is_none());
assert!(value.get("limit").is_none());
assert!(value.get("max_text_chars").is_none());
assert!(value.get("include_stack").is_none());
let round: ConsoleParams = serde_json::from_value(value).unwrap();
assert_eq!(round, params);
}
#[test]
fn console_result_round_trips_with_stack_and_truncation() {
let result = ConsoleResult {
tab_id: 7,
entries: vec![ConsoleEntry {
sequence: 12,
kind: ConsoleEntryKind::Exception,
level: "error".into(),
text: "Uncaught TypeError: x is undefined".into(),
url: Some("https://example.test/app.js".into()),
line: Some(42),
column: Some(7),
timestamp: Some(1234.5),
stack_trace: vec![ConsoleStackFrame {
function_name: Some("render".into()),
url: Some("https://example.test/app.js".into()),
line: Some(42),
column: Some(7),
}],
truncated: true,
}],
next_since: 12,
truncated: true,
};
let value = serde_json::to_value(&result).unwrap();
assert_eq!(value["entries"][0]["kind"], json!("exception"));
assert_eq!(
value["entries"][0]["stack_trace"][0]["function_name"],
json!("render")
);
let round: ConsoleResult = serde_json::from_value(value).unwrap();
assert_eq!(round, result);
}
}
+2
View File
@@ -1,5 +1,6 @@
//! Typed params/results for the 21 `tool.*` RPC methods (§7).
pub mod console;
pub mod dialog;
pub mod human_loop;
pub mod interaction;
@@ -10,6 +11,7 @@ pub mod session;
pub mod tabs;
pub mod waits;
pub use console::*;
pub use dialog::*;
pub use human_loop::*;
pub use interaction::*;