basis_tasks/
lib.rs

1//! The durable task layer over [`basis`]: a filesystem-coordinated lifecycle
2//! for spawned agents, reachable from Rust and not only from a CLI.
3//!
4//! ADR-0019 retired the per-workspace daemon. A task is a directory under one
5//! global data directory; execution belongs to whichever process holds its
6//! `attach.lock` — one writer, ever; liveness belongs to the OS. No verb here
7//! leaves a resident process behind, and no verb takes a lock it does not
8//! need: `send`, `cancel`, `watch`, `list`, and the read-only accessors never
9//! attach at all. [`Tasks`] is the crate's front door; open one and see its
10//! docs for what each verb does and costs.
11//!
12//! Every rule ADR-0017 states is enforced exactly as it was inside the CLI
13//! this crate was extracted from, unchanged: 16 messages to a durable inbox,
14//! 4 KiB bounded summaries, a finite deadline on every unattended task,
15//! downward-only cancellation, and the wait-edge policy that keeps a
16//! `basis wait`-shaped call from ever cycling (a descendant or an independent
17//! root is a safe edge; an ancestor or a peer is not).
18//!
19//! # The environment protocol
20//!
21//! A task's runtime sets up to four environment variables for every command
22//! its turns run (ADR-0018), and this is the one place their names and meanings
23//! are declared — they are read by tools this crate never sees run, so this
24//! is a protocol this crate publishes rather than an implementation detail
25//! it could rename:
26//!
27//! - [`BASIS_TASK_ID`] — this task's own handle. A tool that wants to `send`
28//!   or `ask` its own task — a subagent reporting progress upward, for one —
29//!   reads this rather than being told.
30//! - [`BASIS_DATA_DIR`] — the data directory root [`Tasks::open`] would
31//!   resolve to on its own, named explicitly so a recursive `basis` (or any
32//!   other binary built on this crate) invoked from inside a turn resolves
33//!   the same data directory its parent did, rather than rediscovering one
34//!   from a possibly different environment.
35//! - [`BASIS_PARENT_TASK_ID`] — the parent's handle, present only when the
36//!   task has one. What lets a deeply nested spawn still name its whole
37//!   ownership chain without walking `meta.json` files to find it.
38//! - [`BASIS_HOP`] — the agent-to-agent hop the task's work arrived at,
39//!   present only when it is not 0 (see `RunSpec::with_hop`). What a client
40//!   run from inside a turn adds one to when it hands work to another agent
41//!   (ADR-0030 §9).
42//!
43//! [`current_task`] reads the first of these back, for a host that wants to
44//! know whether *it* is running as a task's tool call.
45
46mod approve;
47mod attach;
48mod builders;
49mod client;
50mod data_dir;
51mod error;
52mod events;
53mod handle;
54mod inbox;
55mod live;
56mod lock;
57mod policy;
58mod spec;
59mod state;
60mod stop;
61mod tasks;
62mod watch;
63
64pub use approve::{Approve, PromptHost, validate_approval};
65pub use attach::POLL;
66pub use builders::configure_builders;
67pub use client::{Reply, Tasks, WaitOutcome};
68pub use error::{Error, Hint};
69pub use handle::TaskHandle;
70pub use live::LiveSink;
71pub use spec::{Continuation, DEFAULT_DEADLINE, RunSpec};
72pub use state::{
73    InboxRecord, MAX_PROMPT, MAX_TASKS, MessageRecord, MessageReply, MessageState, Terminal,
74    TerminalRecord, now_ms,
75};
76pub use stop::Stop;
77pub use tasks::{TaskSummary, probe_state};
78pub use watch::{EventCursor, WatchRecord};
79
80/// This task's own handle — see [`BASIS_TASK_ID`].
81pub const BASIS_TASK_ID: &str = "BASIS_TASK_ID";
82/// The data directory root this task's runtime resolved — see
83/// [`BASIS_DATA_DIR`].
84pub const BASIS_DATA_DIR: &str = "BASIS_DATA_DIR";
85/// This task's parent, when it has one — see [`BASIS_PARENT_TASK_ID`].
86pub const BASIS_PARENT_TASK_ID: &str = "BASIS_PARENT_TASK_ID";
87/// The hop this task's work arrived at, when it is not 0 — see
88/// [`BASIS_HOP`].
89pub const BASIS_HOP: &str = "BASIS_HOP";
90
91/// This process's own task, if it is itself running as one — read from
92/// [`BASIS_TASK_ID`]. `None` for a value that is absent, blank, or does not
93/// fit the task-handle grammar: basis's own runtime always sets a well-formed
94/// one, so a malformed value is not basis's, and treating it as "no current
95/// task" is the safer reading of somebody else's environment variable.
96pub fn current_task() -> Option<TaskHandle> {
97    let value = std::env::var(BASIS_TASK_ID).ok()?;
98    if value.trim().is_empty() {
99        return None;
100    }
101    TaskHandle::parse(value).ok()
102}
basis_tasks/lib.rs

basis_tasks/
lib.rs
