task_runs/
types.rs

1//! Core types for the TaskRun system.
2//!
3//! These mirror the data model in `.yah/docs/working/yah-task-runs.md`.
4//! Intentionally kept free of I/O — the store layer owns persistence.
5//!
6//! The types `TaskRunId`, `Level`, `EventSource`, `ChunkRef`, `Event`,
7//! `Diagnostic`, `Initiator`, and `RunStatus` live in
8//! `crates/yah/observation/` and are re-exported here for backward
9//! compatibility.
10
11use serde::{Deserialize, Serialize};
12use std::path::PathBuf;
13
14// Re-export the hoisted observation types so all existing callers continue to
15// work via `use task_runs::{TaskRunId, Event, ...}`.
16pub use observation::{
17    ChunkRef, Diagnostic, Event, EventScope, EventSource, ForgeId, Initiator, Level, RunStatus,
18    TaskRunId, RESERVED_FIELD_PATHS,
19};
20
21// ─── BeholderStatus ───────────────────────────────────────────────────────────
22
23/// Opaque string surfaced on `TaskRunMeta.beholder_status`.
24///
25/// Examples: `"attached:cargo@1.78"`, `"none:auto"`, `"declined:cargo
26/// reason=\"explicit --message-format=human\""`, `"unknown_format"`,
27/// `"attached:cargo@1.78 rewrite=\"--message-format=json-render-diagnostics\""`.
28#[derive(Debug, Clone, Serialize, Deserialize)]
29pub struct BeholderStatus {
30    pub text: String,
31    /// Args added to argv by a `Rewriter` beholder. `None` for `Parser` mode or
32    /// when no beholder attached.
33    #[serde(skip_serializing_if = "Option::is_none")]
34    pub rewrite_added: Option<Vec<String>>,
35}
36
37impl BeholderStatus {
38    fn make(text: String) -> Self {
39        Self { text, rewrite_added: None }
40    }
41
42    pub fn none_auto() -> Self {
43        Self::make("none:auto".to_string())
44    }
45    /// Bytes-only because the caller explicitly set `BeholderSelect::None`.
46    pub fn none_explicit() -> Self {
47        Self::make("none:explicit".to_string())
48    }
49    pub fn attached(name: &str, version: &str) -> Self {
50        Self::make(format!("attached:{name}@{version}"))
51    }
52    pub fn declined(name: &str, reason: &str) -> Self {
53        Self::make(format!("declined:{name} reason=\"{reason}\""))
54    }
55    /// `BeholderSelect::Force` matched; `matches` predicate agreed.
56    pub fn forced(name: &str, version: &str) -> Self {
57        Self::make(format!("forced:{name}@{version}"))
58    }
59    /// `BeholderSelect::Force` matched; beholder's `matches` would have declined.
60    pub fn forced_against_flags(name: &str, version: &str) -> Self {
61        Self::make(format!("forced-against-flags:{name}@{version}"))
62    }
63    /// `BeholderSelect::Force` matched on a TTY-attached run where a Rewriter
64    /// beholder would normally decline to preserve human output.
65    pub fn forced_against_tty(name: &str, version: &str) -> Self {
66        Self::make(format!("forced-against-tty:{name}@{version}"))
67    }
68    pub fn unknown_format() -> Self {
69        Self::make("unknown_format".to_string())
70    }
71    /// Beholder detected that the tool's output format is unrecognized (schema
72    /// drift). Records which beholder made the call and why.
73    pub fn unknown_format_with_reason(name: &str, reason: &str) -> Self {
74        Self::make(format!("unknown_format:{name} reason=\"{reason}\""))
75    }
76
77    /// Append rewrite info to this status if `added` is non-empty.
78    ///
79    /// Called after a `Rewriter` beholder adjusts argv so agents can see exactly
80    /// what was injected into the command line.
81    pub fn with_rewrite(mut self, added: Vec<String>) -> Self {
82        if !added.is_empty() {
83            let repr = added.join(" ");
84            self.text = format!("{} rewrite=\"{repr}\"", self.text);
85            self.rewrite_added = Some(added);
86        }
87        self
88    }
89}
90
91// ─── TaskRunMeta ──────────────────────────────────────────────────────────────
92
93#[derive(Debug, Clone, Serialize, Deserialize)]
94pub struct TaskRunMeta {
95    pub id: TaskRunId,
96    pub command: String,
97    pub cwd: PathBuf,
98    pub env: Vec<(String, String)>,
99    pub started_at: u64,
100    pub status: RunStatus,
101    pub label: Option<String>,
102    pub initiator: Initiator,
103    pub beholder_status: Option<BeholderStatus>,
104    /// If true, the GC sweep will not drop this run's output during warm rolloff.
105    /// Pinned runs are exempt until explicitly unpinned or archived.
106    #[serde(default)]
107    pub pinned: bool,
108    /// What surface spawned this run. `None` (the default) is an ordinary
109    /// `task.run` job; `Some("terminal")` marks an interactive terminal
110    /// session (SSH / local PTY / camp shell). A generic provenance tag, not
111    /// a UI concept — it lets a consumer (e.g. the desktop terminal rail) list
112    /// just its own runs from `task.list` without scooping up unrelated jobs.
113    #[serde(default)]
114    pub origin: Option<String>,
115    /// PID of the process whose [`crate::TaskDriver`] spawned this run — the
116    /// run's **owner**, not the child.
117    ///
118    /// Recorded so a driver starting up in one process can tell a genuinely
119    /// abandoned run from one a live peer process is still driving. Without
120    /// it, "leftover `Running` rows are stale" is only true when exactly one
121    /// process ever writes the store, and the moment a second one attaches it
122    /// tombstones the first one's live runs. See
123    /// [`crate::driver::StaleRunPolicy`].
124    ///
125    /// `None` for rows written before the column existed, which the policy
126    /// reads as "owner unknown" and treats conservatively (tombstone).
127    #[serde(default)]
128    pub host_pid: Option<u32>,
129}
130
131// ─── Stream ───────────────────────────────────────────────────────────────────
132
133#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
134#[serde(rename_all = "lowercase")]
135pub enum Stream {
136    Stdout,
137    Stderr,
138    Synth,
139}
140
141impl Stream {
142    pub fn as_str(self) -> &'static str {
143        match self {
144            Stream::Stdout => "stdout",
145            Stream::Stderr => "stderr",
146            Stream::Synth => "synth",
147        }
148    }
149}
150
151impl std::str::FromStr for Stream {
152    type Err = String;
153    fn from_str(s: &str) -> Result<Self, Self::Err> {
154        match s {
155            "stdout" => Ok(Stream::Stdout),
156            "stderr" => Ok(Stream::Stderr),
157            "synth" => Ok(Stream::Synth),
158            other => Err(format!("unknown stream: {other}")),
159        }
160    }
161}
162
163// ─── OutputChunk ──────────────────────────────────────────────────────────────
164
165#[derive(Debug, Clone, Serialize, Deserialize)]
166pub struct OutputChunk {
167    pub run_id: TaskRunId,
168    pub seq: u32,
169    pub offset_ms: u32,
170    pub stream: Stream,
171    pub bytes: Vec<u8>,
172}
173
174// ─── SeqRange ─────────────────────────────────────────────────────────────────
175
176/// Inclusive range over chunk `seq` numbers within a single run.
177#[derive(Debug, Clone, Serialize, Deserialize)]
178pub struct SeqRange {
179    pub lo: u32,
180    pub hi: u32,
181}
182
183// ─── Triage (Tier 1.75 — pruner output) ───────────────────────────────────────
184
185/// Pruner output for a run: a list of verbatim chunk ranges + a human-facing
186/// synopsis.
187///
188/// **Agents must read `keep`/`primary` ranges and resolve them to bytes via
189/// `task.lines`. The `synopsis` is for human display only — it can paraphrase
190/// or hallucinate. Never parse it programmatically.**
191#[derive(Debug, Clone, Serialize, Deserialize)]
192pub struct Triage {
193    pub run_id: TaskRunId,
194    pub synopsis: String,
195    pub keep: Vec<KeepRange>,
196    pub primary: SeqRange,
197    pub model: String,
198    pub prompt_version: u32,
199    pub cached_at: u64,
200    pub partial: bool,
201}
202
203#[derive(Debug, Clone, Serialize, Deserialize)]
204pub struct KeepRange {
205    pub range: SeqRange,
206    pub reason: String,
207}
task_runs/types.rs

task_runs/
types.rs
