Skip to main content

taskfast_cli/cmd/events/
poll.rs

1// SPDX-License-Identifier: MIT
2//! `taskfast events poll` — single-page read over `GET /agents/me/events`.
3//!
4//! The SDK also offers `stream_events` (long-running cursor chase);
5//! the polling subcommand stays one-shot because a JSON-lines follow
6//! mode doesn't mix with the envelope-per-invocation contract. Live
7//! tailing lives in [`super::stream`] over WebSocket instead.
8//!
9//! # Cursor persistence
10//!
11//! With `--cursor` absent, the previous invocation's `next_cursor` is
12//! read from `<config_dir>/events.cursor` so back-to-back polls in an
13//! agent loop resume past the last batch without orchestrator
14//! bookkeeping. After a successful poll the new `next_cursor` is
15//! written back. `--cursor -` and `TASKFAST_NO_CURSOR_STATE=1` both
16//! disable read+write for ad-hoc inspection runs that shouldn't
17//! mutate the persisted offset.
18
19use clap::Parser;
20use serde_json::json;
21
22use super::super::{CmdError, CmdResult, Ctx};
23use super::intake::EventIntake;
24use crate::envelope::Envelope;
25
26use taskfast_agent::events::list_events_page_tolerant;
27
28#[derive(Debug, Parser)]
29pub struct PollArgs {
30    /// Opaque pagination cursor from a previous response's `next_cursor`.
31    /// Pass `-` to bypass the persisted cursor file (no read, no write)
32    /// for one-shot inspection without mutating the agent loop's offset.
33    #[arg(long)]
34    pub cursor: Option<String>,
35
36    /// Max events per page. Defaults to 25 — comfortable batch for an
37    /// agent loop tick without dragging in a wall of backlog.
38    #[arg(long, default_value_t = 25)]
39    pub limit: i64,
40}
41
42pub async fn run(ctx: &Ctx, args: PollArgs) -> CmdResult {
43    let mut intake = EventIntake::from_ctx(ctx, args.cursor.as_deref());
44    let effective_cursor = intake.effective_cursor().map(str::to_string);
45
46    let client = ctx.client()?;
47    let page = list_events_page_tolerant(&client, effective_cursor.as_deref(), Some(args.limit))
48        .await
49        .map_err(CmdError::from)?;
50
51    let outcome = intake.ingest_poll_page(page);
52
53    if let Err(e) = intake.commit() {
54        intake.warn(&format!("failed to persist events cursor: {e}"));
55    }
56
57    let unparseable: Vec<serde_json::Value> = outcome
58        .unparseable_events
59        .iter()
60        .map(|u| json!({ "raw": u.raw, "error": u.error }))
61        .collect();
62
63    Ok(Envelope::success(
64        ctx.environment,
65        ctx.dry_run,
66        json!({
67            "events": outcome.accepted_events,
68            "unparseable": unparseable,
69            "meta": outcome.meta,
70        }),
71    ))
72}
73
74#[cfg(test)]
75mod tests {
76    use super::*;
77    use std::path::PathBuf;
78
79    fn ctx_with_config(path: PathBuf) -> Ctx {
80        Ctx {
81            config_path: path,
82            ..Default::default()
83        }
84    }
85
86    #[test]
87    fn dash_sentinel_disables_both_request_and_persistence() {
88        let ctx = ctx_with_config(PathBuf::from("/tmp/x/.taskfast/config.json"));
89        let intake = EventIntake::from_ctx(&ctx, Some("-"));
90        assert!(!intake.persistence_enabled());
91        assert_eq!(intake.effective_cursor(), None);
92    }
93
94    #[test]
95    fn explicit_cursor_uses_passed_value() {
96        let ctx = ctx_with_config(PathBuf::from("/tmp/x/.taskfast/config.json"));
97        let intake = EventIntake::from_ctx(&ctx, Some("abc"));
98        assert_eq!(intake.effective_cursor(), Some("abc"));
99        assert!(intake.persistence_enabled());
100    }
101
102    #[test]
103    fn explicit_cursor_still_sent_when_persistence_unavailable() {
104        let ctx = ctx_with_config(PathBuf::from("/dev/null"));
105        let intake = EventIntake::from_ctx(&ctx, Some("abc"));
106        assert_eq!(intake.effective_cursor(), Some("abc"));
107        assert!(!intake.persistence_enabled());
108    }
109
110    #[test]
111    fn dev_null_config_disables_persistence() {
112        let ctx = ctx_with_config(PathBuf::from("/dev/null"));
113        let intake = EventIntake::from_ctx(&ctx, None);
114        assert_eq!(intake.effective_cursor(), None);
115        assert!(!intake.persistence_enabled());
116    }
117
118    #[test]
119    fn write_then_read_round_trips() {
120        let dir = tempfile::tempdir().unwrap();
121        let cfg = dir.path().join("config.json");
122        let ctx = ctx_with_config(cfg);
123        let mut intake = EventIntake::from_ctx(&ctx, None);
124        assert!(intake.persistence_enabled());
125        let _ = intake.ingest_batch(
126            Vec::new(),
127            Vec::new(),
128            taskfast_client::api::types::PaginatedMeta {
129                has_more: false,
130                next_cursor: Some("xyz".to_string()),
131                total_count: Some(0),
132            },
133        );
134        intake.commit().unwrap();
135        let intake2 = EventIntake::from_ctx(&ctx, None);
136        assert_eq!(intake2.effective_cursor(), Some("xyz"));
137    }
138
139    #[test]
140    fn persist_none_preserves_last_known_cursor() {
141        let dir = tempfile::tempdir().unwrap();
142        let cfg = dir.path().join("config.json");
143        let ctx = ctx_with_config(cfg);
144        let mut intake = EventIntake::from_ctx(&ctx, None);
145        let _ = intake.ingest_batch(
146            Vec::new(),
147            Vec::new(),
148            taskfast_client::api::types::PaginatedMeta {
149                has_more: false,
150                next_cursor: Some("abc".to_string()),
151                total_count: Some(0),
152            },
153        );
154        intake.commit().unwrap();
155
156        let mut intake2 = EventIntake::from_ctx(&ctx, None);
157        let _ = intake2.ingest_batch(
158            Vec::new(),
159            Vec::new(),
160            taskfast_client::api::types::PaginatedMeta {
161                has_more: false,
162                next_cursor: None,
163                total_count: Some(0),
164            },
165        );
166        intake2.commit().unwrap();
167
168        let intake3 = EventIntake::from_ctx(&ctx, None);
169        assert_eq!(intake3.effective_cursor(), Some("abc"));
170    }
171}