Skip to content

Releases

v0.19.0

Choose a tag to compare

@github-actions github-actions released this 29 Oct 18:49

Breaking changes

On the wire, for agents and the programs that read agcli output:

  • A secret in argv is no longer echoed. The command field, 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=value and
    -x value: app run --passphrase=hunter2 reports
    app run --passphrase=<redacted>. The PARSE_ERROR for a malformed token
    such as -abc=5 quotes 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_FLAG and PARSE_ERROR text. The type's own parse error is
    left out of arg_parse and flag_parse errors 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 in command.

    In Rust, Invocation::command_line returns the masked line inside a
    handler, as the envelope shows it; Invocation::parse still 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 pat is
    INVALID_FLAG "flag --max does not reach raw command grep",
    app --bogus grep pat and calc --bogus add 1 2 are UNKNOWN_FLAG, and
    ops --lines logs app runs logs, which answers that --lines was given
    no value. All of these used to be UNKNOWN_COMMAND for the next word.
    Write --flag=value to pass a value spelled like a command.

    app --name status status, which set --name to status, becomes
    app --name=status status. Under without_reserved_flags(),
    app --profile grep grep pat now hands raw grep ["grep", "pat"],
    not ["pat"].

Added

  • Command::secret(name) masks a declared flag or positional as
    <redacted> in the command field and every error's text. The handler
    still reads the real value. name is how the usage spells it, without
    dashes or angle brackets.
  • AgentCli::redact_arg(hook) takes Fn(&str) -> Option<String>, applied
    to each argv element before an envelope echoes it, for patterns only the
    app knows, such as field=value assignments. See "Secrets in argv" in the
    README.
  • audit() reports UNDECLARED_SECRET, a Command::secret name that no
    command on its path declares (a flag counts from a parent's usage or a
    subcommand's), and SECRET_ON_RAW_COMMAND, a secret marked on a raw
    command, whose tokens are never parsed. Both are errors, since neither masks
    anything. SECRET_AFTER_OPTIONAL warns 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

Choose a tag to compare

@github-actions github-actions released this 24 Oct 21:55

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 is Clone and Debug, 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")?; .. }).

  • ExecutionContext is gone, with run_env_with_context and
    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_argv is run.

    cli.run_argv(["app", "status"]).await becomes
    cli.run(["app", "status"]).await.

  • Under run_env, a handler panic ends the process from a panic hook.
    catch_unwind is gone. The hook writes the HANDLER_PANIC envelope and
    exits with code 1, so run_env does not return. The Fixed section lists
    what the hook covers.

    Code after cli.run_env().await no 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_handler and
    raw_handler each fill it, and the last call wins. A raw handler used to
    win over a normal one whatever the order, and audit() reported
    RAW_COMMAND_HAS_HANDLER; that finding is gone. doctor_with replaces
    whatever handler its command had.

    .raw_handler(raw).handler(normal) runs normal.

  • Streaming moves into the framework. Command::stream_handler hands the
    handler a StreamWriter for its events, and the framework writes the one
    terminal line from the handler's return value. NdjsonEmitter,
    FlushPolicy, StreamEmitError, the terminal StreamEvent::Result and
    StreamEvent::Error variants, StreamEvent::result_from_envelope and
    StreamEvent::error_from_envelope are gone. StreamEvent variants lose
    their ts: the writer stamps each event from the run's clock and flushes
    every line. StreamWriter::emit takes &self, and the writer is Clone,
    so a task the handler spawns can emit through a clone; a clone kept past
    the handler's return is refused with StreamWriteError::Closed.

    emitter.emit(StreamEvent::Step { .., ts }).await?; emitter.emit_result(envelope).await?
    becomes out.emit(&StreamEvent::Step { .. })?; Ok(CommandOutput::new(..)).

  • ActionParam::default is default_value. The builder shadowed the
    derived Default, so ActionParam::default() did not compile. The wire
    key stays default.

    ActionParam::new().default("worker") becomes
    ActionParam::new().default_value("worker").

  • tokio is no longer a dependency. Dispatch stays async, and any executor
    can drive run_env and run. truncate_lines_with_file and
    TruncatedEntries::cleanup are synchronous, and read_stdin is 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_file refuses a max_lines of 0 and an invalid
    file_prefix
    with io::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_request is gone.

    Check::new("ping", || Box::pin(async { CheckResult::pass() })) becomes
    Check::new("ping", |_req| async { CheckResult::pass() }).

  • ExitCode is a u8 newtype, not a namespace of i32 constants.
    CommandError::exit_code, CommandOutput::exit_code, Check::exit_code,
    raw handlers, Execution::exit_code, Execution::print and
    Envelope::exit_code take or return it. ExitCode::new builds any status
    and get reads it. TryFrom<i32> fails outside 0..=255, so nothing is
    masked any more. From<ExitCode> for std::process::ExitCode lets main
    return one.

    assert_eq!(run.exit_code(), 0) becomes
    assert_eq!(run.exit_code(), ExitCode::SUCCESS).

  • Error codes are ErrorCode values, and CommandError::new takes the code
    first
    , so the code, the message and the fix cannot trade places. The
    framework's codes are constants such as ErrorCode::INVALID_ARG; a
    command names its own with ErrorCode::new, or ErrorCode::owned for a
    String built at run time (format!("HTTP_{status}")). A code is never
    empty: both constructors panic on one. CommandError::code and
    ErrorBody::code are ErrorCode.

    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, retryable and data builders are
    private. SuccessEnvelope, ErrorEnvelope, ErrorBody and
    CommandError are #[non_exhaustive], so CommandError::new, which
    requires a fix, is the only way to build an error. Read envelopes from
    Execution::envelope, or decode them with the deserialize feature.

    ErrorEnvelope::new(command, message, code, fix, actions) becomes
    Err(CommandError::new(code, message, fix)) from a handler.

  • Envelope timestamps are Timestamp values. SuccessEnvelope::timestamp
    and ErrorEnvelope::timestamp are an agcli::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
    carries timestamp: Timestamp; its wire key stays ts.
    SuccessEnvelope gains select_warning.

    envelope.timestamp (a u64) becomes envelope.timestamp.epoch_secs().

  • Invocation::parse(args, is_bool) replaces parse_invocation and
    parse_invocation_with_bool_flags.
    Invocation::into_command_line is
    gone, positional_indices is private, and ParseInvocationError gains
    RepeatedFlag.

    parse_invocation_with_bool_flags(args, |flag| flag == "force") becomes
    Invocation::parse(args, |flag| flag == "force").

  • AgentCli::reserved_flags(false) is without_reserved_flags(). true
    was the default and meant nothing.

    .reserved_flags(false) becomes .without_reserved_flags().

  • CommandRequest::prompt is gone, and CommandRequest::select returns an
    iterator
    over the requested fields, empty when --select is absent.

    req.select().unwrap_or_default() becomes
    req.select().collect::<Vec<_>>().

  • CommandOutput::from_serializable is try_from_serializable, so the
    name says it can fail.

    CommandOutput::from_serializable(&value) becomes
    CommandOutput::try_from_serializable(&value).

  • CheckResult::failed and CheckResult::skipped are is_failed and
    is_skipped
    , named like is_ok.

    result.failed() becomes result.is_failed().

  • reserved_flag_names() no longer lists version, and lists the flags
    in the order the root tree documents them. --help, -h, --version
    and -V are reserved always, apart from the agent flags.

    reserved_flag_names().contains(&"version") is now false.

  • More public types are #[non_exhaustive]: the structs NextAction,
    ActionParam, TruncatedEntries, CheckResult, AuditFinding and
    AuditReport, and the enums ParseInvocationError and
    StreamWriteError. Get the structs from NextAction::new,
    ActionParam::new and the other functions that return them, and give a
    match on the enums a wildcard arm.

    CheckResult { status: CheckStatus::Pass, detail: None, fix: None }
    becomes CheckResult::pass().

  • Builder mistakes panic in every build. A duplicate name in
    AgentCli::command or Command::subcommand, and
    CommandError::exit_code(ExitCode::SUCCESS), were debug_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 a total below the
    item count, which reported count: 3, total: 1, truncated: false, and
    AgentCli::skill() on a CLI name that is not a slug, whose frontmatter
    name and --install directory no harness accepts. The
    SKILL_NAME_INVALID audit finding is gone with it: such a CLI cannot be
    built. Under run_env, an assert inside a handler becomes a
    HANDLER_PANIC envelope.

    .command(status).command(status_again) panics in release builds too.

  • The deserialize feature is strict about the keys it knows. A missing
    or malformed known key is an error: no epoch-integer timestamp, no
    unparseable timestamp read as 0, no timestamp naming an impossible date
    such as 2026-02-29, and no default for a missing exit_code, dropped
    or event field. Shapes the framework never writes are refused too: a
    null for schema_version, select_warning or data (the ke...

Read more

v0.17.0

Choose a tag to compare

@github-actions github-actions released this 21 Aug 09:01

0.17.0 - 2026-08-21

Features

  • A doctor command the consumer owns, and structured error payloads (740235d)
  • Help becomes a skill, so an agent can bootstrap from the binary (9b65279)

Miscellaneous

v0.15.0

Choose a tag to compare

@github-actions github-actions released this 19 Aug 18:42

0.15.0 - 2026-08-19

Bug Fixes

  • A raw command owns its argv wherever its name sits on the line (20516bb)

Features

  • Raw passthrough commands and a third doctor outcome (5f33a6f)

Miscellaneous

v0.14.0

Choose a tag to compare

@github-actions github-actions released this 28 Jul 15:00

0.14.0 - 2026-07-28

Features

  • List results advertise row schema and teach --select (f4874a8)

Miscellaneous

Testing

  • Kill top-3 surviving mutants via cargo-mutants triage (a6fa40e)
  • Kill 3 surviving mutants in cli.rs via mutation triage (a15bae9)

v0.13.0

Choose a tag to compare

@github-actions github-actions released this 11 Jun 22:37

0.13.0 - 2026-06-11

Documentation

  • Agent-ergonomics audit workspace for pass 1 (86c6aca)

Features

  • Agent-ergonomics pass 2 — arity guard, contract export, golden envelopes, hardening fixes (6128d32)

Miscellaneous

v0.12.0

Choose a tag to compare

@github-actions github-actions released this 11 Jun 22:06

0.12.0 - 2026-06-11

Features

  • Agent-ergonomics hardening — unknown-flag rejection, dry-run gate, help/version, exit-code consistency (690b7da)

v0.11.0

Choose a tag to compare

@github-actions github-actions released this 10 Jun 12:08

0.11.0 - 2026-06-10

Features

  • Serialize envelope timestamp as RFC 3339 UTC string (0a01326)

Miscellaneous

v0.10.2

Choose a tag to compare

@github-actions github-actions released this 09 Jun 14:54

0.10.2 - 2026-06-09

Documentation

  • Migrate AGENTS.md calculator example to async 0.10.1 API (5c88818)

Features

  • Inline valid names and did-you-mean nudge in unknown-command fixes (5e6d09d)

Miscellaneous

v0.10.1

Choose a tag to compare

@github-actions github-actions released this 01 Jun 17:27

0.10.1 - 2026-06-01

Documentation

  • Drop build-machine codegen and PGO tuning notes (8a91c1b)

Miscellaneous