Repository navigation
Releases
v0.19.0
Breaking changes
On the wire, for agents and the programs that read agcli output:
-
A secret in argv is no longer echoed. The
commandfield, and the error
text that quotes an argument, mask the value of any flag the command's
usage does not declare, in--flag=value,--flag value,-x=valueand
-x value:app run --passphrase=hunter2reports
app run --passphrase=<redacted>. ThePARSE_ERRORfor a malformed token
such as-abc=5quotes it as-abc=<redacted>, a line that fails to
parse masks every token that is not a flag name or a command name, and the
flag values in a raw command's tokens, and before its name, are masked.
A token right after a masked bare flag is masked whole, even when it
starts with a dash, and the flags it would set are left out of
UNKNOWN_FLAGandPARSE_ERRORtext. The type's own parse error is
left out ofarg_parseandflag_parseerrors for a masked value, and
error text that quotes a hook-rewritten argument shows<redacted>. A line that used to
rerun as printed no longer does when it carried such a value: declare the
flag in the usage (--passphrase=<value>) to keep its value incommand.In Rust,
Invocation::command_linereturns the masked line inside a
handler, as the envelope shows it;Invocation::parsestill returns it
verbatim. -
A command's name is never a flag's value. A bare flag (no
=) takes
the next token as its value only when that token does not name a
command where a command name can go; otherwise the flag is given no
value and the token is the command. A flag misplaced before a command's
name now gets the error that names it:app --max grep patis
INVALID_FLAG"flag --max does not reach raw commandgrep",
app --bogus grep patandcalc --bogus add 1 2areUNKNOWN_FLAG, and
ops --lines logs apprunslogs, which answers that--lineswas given
no value. All of these used to beUNKNOWN_COMMANDfor the next word.
Write--flag=valueto pass a value spelled like a command.app --name status status, which set--nametostatus, becomes
app --name=status status. Underwithout_reserved_flags(),
app --profile grep grep patnow hands rawgrep["grep", "pat"],
not["pat"].
Added
Command::secret(name)masks a declared flag or positional as
<redacted>in thecommandfield and every error's text. The handler
still reads the real value.nameis how the usage spells it, without
dashes or angle brackets.AgentCli::redact_arg(hook)takesFn(&str) -> Option<String>, applied
to each argv element before an envelope echoes it, for patterns only the
app knows, such asfield=valueassignments. See "Secrets in argv" in the
README.audit()reportsUNDECLARED_SECRET, aCommand::secretname that no
command on its path declares (a flag counts from a parent's usage or a
subcommand's), andSECRET_ON_RAW_COMMAND, a secret marked on a raw
command, whose tokens are never parsed. Both are errors, since neither masks
anything.SECRET_AFTER_OPTIONALwarns about a secret positional after
an optional one: when the optional is left out, every positional from the
first optional on is masked.
v0.18.0
This release redesigns the Rust API. Handlers are plain async closures, agcli
no longer depends on tokio, the framework writes a streaming command's terminal
line, and exit and error codes are types. The wire contract is stricter: a
non-boolean value, a repeated flag or a malformed SOURCE_DATE_EPOCH is an
error, not a guess. Breaking changes are a minor bump pre-1.0.
Breaking changes
In Rust:
-
Handlers are plain async closures over an owned
CommandRequest. The
request has no lifetime and isCloneandDebug, so a handler moves it
into its future, and the framework boxes the future..handler(|req, _ctx| { let a = req.arg_parse::<f64>(0, "a"); Box::pin(async move { .. }) })
becomes.handler(|req| async move { let a: f64 = req.arg_parse(0, "a")?; .. }). -
ExecutionContextis gone, withrun_env_with_contextand
run_argv_with_context. Share state the way any closure does, by
capturing it.ctx.set("seen", value)becomes a write through a captured
Arc<Mutex<_>>. -
run_argvisrun.cli.run_argv(["app", "status"]).awaitbecomes
cli.run(["app", "status"]).await. -
Under
run_env, a handler panic ends the process from a panic hook.
catch_unwindis gone. The hook writes theHANDLER_PANICenvelope and
exits with code 1, sorun_envdoes not return. The Fixed section lists
what the hook covers.Code after
cli.run_env().awaitno longer runs when a handler panics. -
Raw handlers take the argv tail by value and resolve to an
ExitCode..raw_handler(|args, _ctx| { let args = args.to_vec(); Box::pin(async move { ..; 0 }) })
becomes.raw_handler(|args| async move { ..; ExitCode::SUCCESS }). -
A command has one handler slot.
handler,stream_handlerand
raw_handlereach fill it, and the last call wins. A raw handler used to
win over a normal one whatever the order, andaudit()reported
RAW_COMMAND_HAS_HANDLER; that finding is gone.doctor_withreplaces
whatever handler its command had..raw_handler(raw).handler(normal)runsnormal. -
Streaming moves into the framework.
Command::stream_handlerhands the
handler aStreamWriterfor its events, and the framework writes the one
terminal line from the handler's return value.NdjsonEmitter,
FlushPolicy,StreamEmitError, the terminalStreamEvent::Resultand
StreamEvent::Errorvariants,StreamEvent::result_from_envelopeand
StreamEvent::error_from_envelopeare gone.StreamEventvariants lose
theirts: the writer stamps each event from the run's clock and flushes
every line.StreamWriter::emittakes&self, and the writer isClone,
so a task the handler spawns can emit through a clone; a clone kept past
the handler's return is refused withStreamWriteError::Closed.emitter.emit(StreamEvent::Step { .., ts }).await?; emitter.emit_result(envelope).await?
becomesout.emit(&StreamEvent::Step { .. })?; Ok(CommandOutput::new(..)). -
ActionParam::defaultisdefault_value. The builder shadowed the
derivedDefault, soActionParam::default()did not compile. The wire
key staysdefault.ActionParam::new().default("worker")becomes
ActionParam::new().default_value("worker"). -
tokio is no longer a dependency. Dispatch stays async, and any executor
can driverun_envandrun.truncate_lines_with_fileand
TruncatedEntries::cleanupare synchronous, andread_stdinis gone.truncate_lines_with_file(lines, 20, "logs").await?becomes
truncate_lines_with_file(lines, 20, "logs")?, and
agcli::read_stdin().await?becomes
std::io::read_to_string(std::io::stdin())?. -
truncate_lines_with_filerefuses amax_linesof 0 and an invalid
file_prefixwithio::ErrorKind::InvalidInput, before writing
anything. It used to treat 0 as 1 and replace an invalid prefix with
agcli-output. A valid prefix is non-empty ASCII letters, digits,-and
_.truncate_lines_with_file(lines, 0, "logs")returns an error. -
Doctor checks have one constructor, and it takes the request.
Check::with_requestis gone.Check::new("ping", || Box::pin(async { CheckResult::pass() }))becomes
Check::new("ping", |_req| async { CheckResult::pass() }). -
ExitCodeis au8newtype, not a namespace ofi32constants.
CommandError::exit_code,CommandOutput::exit_code,Check::exit_code,
raw handlers,Execution::exit_code,Execution::printand
Envelope::exit_codetake or return it.ExitCode::newbuilds any status
andgetreads it.TryFrom<i32>fails outside0..=255, so nothing is
masked any more.From<ExitCode> for std::process::ExitCodeletsmain
return one.assert_eq!(run.exit_code(), 0)becomes
assert_eq!(run.exit_code(), ExitCode::SUCCESS). -
Error codes are
ErrorCodevalues, andCommandError::newtakes the code
first, so the code, the message and the fix cannot trade places. The
framework's codes are constants such asErrorCode::INVALID_ARG; a
command names its own withErrorCode::new, orErrorCode::ownedfor a
Stringbuilt at run time (format!("HTTP_{status}")). A code is never
empty: both constructors panic on one.CommandError::codeand
ErrorBody::codeareErrorCode.CommandError::new("no such issue", "NOT_FOUND", "Check the id")becomes
CommandError::new(ErrorCode::new("NOT_FOUND"), "no such issue", "Check the id"). -
The framework builds every envelope.
SuccessEnvelope::new,
ErrorEnvelope::new,ErrorBody::new, and the envelopes'
schema_version,exit_code,retryableanddatabuilders are
private.SuccessEnvelope,ErrorEnvelope,ErrorBodyand
CommandErrorare#[non_exhaustive], soCommandError::new, which
requires a fix, is the only way to build an error. Read envelopes from
Execution::envelope, or decode them with thedeserializefeature.ErrorEnvelope::new(command, message, code, fix, actions)becomes
Err(CommandError::new(code, message, fix))from a handler. -
Envelope timestamps are
Timestampvalues.SuccessEnvelope::timestamp
andErrorEnvelope::timestampare anagcli::Timestamp: a second from
1970-01-01T00:00:00Z to 9999-12-31T23:59:59Z that displays and serializes
as the RFC 3339 string and parses back strictly.StreamLine::Event
carriestimestamp: Timestamp; its wire key staysts.
SuccessEnvelopegainsselect_warning.envelope.timestamp(au64) becomesenvelope.timestamp.epoch_secs(). -
Invocation::parse(args, is_bool)replacesparse_invocationand
parse_invocation_with_bool_flags.Invocation::into_command_lineis
gone,positional_indicesis private, andParseInvocationErrorgains
RepeatedFlag.parse_invocation_with_bool_flags(args, |flag| flag == "force")becomes
Invocation::parse(args, |flag| flag == "force"). -
AgentCli::reserved_flags(false)iswithout_reserved_flags().true
was the default and meant nothing..reserved_flags(false)becomes.without_reserved_flags(). -
CommandRequest::promptis gone, andCommandRequest::selectreturns an
iterator over the requested fields, empty when--selectis absent.req.select().unwrap_or_default()becomes
req.select().collect::<Vec<_>>(). -
CommandOutput::from_serializableistry_from_serializable, so the
name says it can fail.CommandOutput::from_serializable(&value)becomes
CommandOutput::try_from_serializable(&value). -
CheckResult::failedandCheckResult::skippedareis_failedand
is_skipped, named likeis_ok.result.failed()becomesresult.is_failed(). -
reserved_flag_names()no longer listsversion, and lists the flags
in the order the root tree documents them.--help,-h,--version
and-Vare reserved always, apart from the agent flags.reserved_flag_names().contains(&"version")is nowfalse. -
More public types are
#[non_exhaustive]: the structsNextAction,
ActionParam,TruncatedEntries,CheckResult,AuditFindingand
AuditReport, and the enumsParseInvocationErrorand
StreamWriteError. Get the structs fromNextAction::new,
ActionParam::newand the other functions that return them, and give a
matchon the enums a wildcard arm.CheckResult { status: CheckStatus::Pass, detail: None, fix: None }
becomesCheckResult::pass(). -
Builder mistakes panic in every build. A duplicate name in
AgentCli::commandorCommand::subcommand, and
CommandError::exit_code(ExitCode::SUCCESS), weredebug_assert!s: a
release build silently replaced the first command, or printed an error
envelope with exit code 0. Two more mistakes panic the same way:
CommandOutput::list_truncated(items, total)with atotalbelow the
item count, which reportedcount: 3, total: 1, truncated: false, and
AgentCli::skill()on a CLI name that is not a slug, whose frontmatter
nameand--installdirectory no harness accepts. The
SKILL_NAME_INVALIDaudit finding is gone with it: such a CLI cannot be
built. Underrun_env, an assert inside a handler becomes a
HANDLER_PANICenvelope..command(status).command(status_again)panics in release builds too. -
The
deserializefeature is strict about the keys it knows. A missing
or malformed known key is an error: no epoch-integertimestamp, no
unparseable timestamp read as 0, no timestamp naming an impossible date
such as 2026-02-29, and no default for a missingexit_code,dropped
or event field. Shapes the framework never writes are refused too: a
nullforschema_version,select_warningordata(the ke...