Skip to main content

taskfast_cli/cmd/events/
mod.rs

1// SPDX-License-Identifier: MIT
2//! `taskfast events` — lifecycle event read/stream/ack + AsyncAPI schema.
3//!
4//! Subcommands:
5//!
6//! * [`poll`] — one-shot `GET /api/agents/me/events` (cursor-paginated
7//!   read). Envelope-wrapped like every other subcommand.
8//! * [`stream`] — long-running WebSocket to `/socket/agent` that emits
9//!   one JSONL line per event on stdout. Bypasses the envelope — stdout
10//!   is the contract. Ack via `taskfast events ack <id>` from a
11//!   separate process.
12//! * [`ack`] — `POST /api/agents/me/events/:id/ack`. Advances the
13//!   server-side cursor and releases the in-flight slot so the next
14//!   event can be pushed on the live stream.
15//! * [`schema`] — `GET /api/asyncapi.json`. Prints the full AsyncAPI
16//!   2.6 document or filters to a single event type via `--event`.
17
18use clap::Subcommand;
19
20use super::{CmdError, CmdResult, Ctx};
21
22pub mod ack;
23pub mod poll;
24pub mod schema;
25pub mod stream;
26
27pub use ack::AckArgs;
28pub use poll::PollArgs;
29pub use schema::SchemaArgs;
30pub use stream::StreamArgs;
31
32#[derive(Debug, Subcommand)]
33pub enum Command {
34    /// GET /agents/me/events — one page of lifecycle events.
35    Poll(PollArgs),
36    /// Stream lifecycle events over WebSocket as JSONL on stdout.
37    ///
38    /// Bypasses the JSON envelope: every line is either an event
39    /// payload or a sentinel (`{"sentinel":"connected"}`,
40    /// `{"sentinel":"reconnecting"}`, `{"sentinel":"resumed"}`,
41    /// `{"sentinel":"closing"}`). Ack each event from a separate
42    /// process via `taskfast events ack <id>`.
43    Stream(StreamArgs),
44    /// POST /agents/me/events/:id/ack — advance cursor + release
45    /// in-flight slot on the live stream.
46    Ack(AckArgs),
47    /// GET /asyncapi.json — AsyncAPI 2.6 schema for the event stream.
48    Schema(SchemaArgs),
49}
50
51/// Dispatch non-stream subcommands. `Stream` is handled in `main.rs`
52/// because it writes JSONL directly to stdout and must bypass the
53/// envelope wrapper.
54pub async fn run(ctx: &Ctx, cmd: Command) -> CmdResult {
55    match cmd {
56        Command::Poll(a) => poll::run(ctx, a).await,
57        Command::Ack(a) => ack::run(ctx, a).await,
58        Command::Schema(a) => schema::run(ctx, a).await,
59        Command::Stream(_) => Err(CmdError::Usage(
60            "`events stream` must be dispatched by main.rs (bypass envelope)".into(),
61        )),
62    }
63}