heddle_cli_args/cli/cli_args/
commands_agent.rs

1// SPDX-License-Identifier: Apache-2.0
2//! `heddle agent` — agent-loop affordances.
3//!
4//! `agent serve` runs a local-only gRPC daemon
5//! over a Unix-domain socket inside the repo's `.heddle/sockets/`. The
6//! daemon hosts agent services (state-review, discussion, signal,
7//! operation-log query, timeline, hook) so a tight agent loop avoids
8//! per-command process startup latency.
9//!
10//! `heddle agent serve` is intentionally distinct from `heddle daemon`,
11//! which controls the FUSE mount daemon — different subsystem, different
12//! UX. `heddle help daemon` contrasts the two.
13
14use std::path::PathBuf;
15
16use clap::Subcommand;
17
18use super::commands_args::{
19    AgentApiListArgs, AgentCaptureArgs, AgentFanoutPlanArgs, AgentFanoutStartArgs,
20    AgentHeartbeatArgs, AgentPresenceCompleteArgs, AgentPresenceExplainArgs, AgentPresenceListArgs,
21    AgentPresenceShowArgs, AgentProvenanceBeginArgs, AgentProvenanceEndArgs,
22    AgentProvenanceListArgs, AgentProvenanceSegmentArgs, AgentProvenanceShowArgs, AgentReadyArgs,
23    AgentReleaseArgs, AgentReserveArgs, AgentTaskCreateArgs, AgentTaskListArgs, AgentTaskShowArgs,
24    AgentTaskUpdateArgs,
25};
26
27#[derive(Clone, Debug, Subcommand)]
28pub enum AgentCommands {
29    /// Run the local agent gRPC daemon in the foreground.
30    ///
31    /// The daemon binds a Unix socket inside the repo's `.heddle/sockets/`
32    /// directory and serves local same-user CLI calls.
33    Serve(AgentServeArgs),
34
35    /// Report whether the local agent daemon is running for this repo.
36    Status,
37
38    /// Ask the running daemon to drain and exit.
39    Stop,
40
41    // --- Reservation API (orchestration surface) ----------------
42    // The variants below are the stable JSON API that orchestrators
43    // (Claude Code subagents, codex harnesses, etc.) call to
44    // coordinate parallel writers on the same repo. Distinct from
45    // the daemon-control variants above: these are one-shot CLI
46    // calls that mutate writer leases and actor presence.
47    /// Atomically reserve a thread for one writer.
48    Reserve(AgentReserveArgs),
49
50    /// Update reservation heartbeat.
51    Heartbeat(AgentHeartbeatArgs),
52
53    /// Capture under a token-authenticated writer lease.
54    Capture(AgentCaptureArgs),
55
56    /// Mark a reservation's thread ready for integration.
57    Ready(AgentReadyArgs),
58
59    /// Release a reservation (status: complete | abandoned).
60    Release(AgentReleaseArgs),
61
62    /// List agent reservations (optionally filtered to alive ones).
63    List(AgentApiListArgs),
64
65    /// Manage local agent task assignments.
66    #[command(subcommand)]
67    Task(AgentTaskCommands),
68
69    /// Plan and start native fan-out lanes.
70    #[command(subcommand)]
71    Fanout(AgentFanoutCommands),
72
73    /// Inspect attribution and work context for local agents.
74    #[command(subcommand)]
75    Presence(AgentPresenceCommands),
76
77    /// Record provider, model, and policy provenance across an agent run.
78    #[command(subcommand)]
79    Provenance(AgentProvenanceCommands),
80}
81
82#[derive(Clone, Debug, Subcommand)]
83pub enum AgentPresenceCommands {
84    /// List agent presence records known to this repository.
85    List(AgentPresenceListArgs),
86
87    /// Show the current or selected agent presence record.
88    Show(AgentPresenceShowArgs),
89
90    /// Explain why Heddle attached the current or selected presence record.
91    Explain(AgentPresenceExplainArgs),
92
93    /// Mark the current or selected presence record complete.
94    Complete(AgentPresenceCompleteArgs),
95}
96
97#[derive(Clone, Debug, Subcommand)]
98pub enum AgentProvenanceCommands {
99    /// Begin a provider/model provenance session.
100    Begin(AgentProvenanceBeginArgs),
101
102    /// Record a provider, model, or policy change within the current session.
103    Segment(AgentProvenanceSegmentArgs),
104
105    /// End the current or selected provenance session.
106    End(AgentProvenanceEndArgs),
107
108    /// Show the current or selected provenance session.
109    Show(AgentProvenanceShowArgs),
110
111    /// List provenance sessions.
112    List(AgentProvenanceListArgs),
113}
114
115#[derive(Clone, Debug, Subcommand)]
116pub enum AgentTaskCommands {
117    /// Create a local agent task assignment.
118    Create(AgentTaskCreateArgs),
119
120    /// List local agent task assignments.
121    List(AgentTaskListArgs),
122
123    /// Show one local agent task assignment.
124    Show(AgentTaskShowArgs),
125
126    /// Update one local agent task assignment.
127    Update(AgentTaskUpdateArgs),
128}
129
130#[derive(Clone, Debug, Subcommand)]
131pub enum AgentFanoutCommands {
132    /// Preview fan-out lane setup and return commands without writing.
133    Plan(AgentFanoutPlanArgs),
134
135    /// Create task assignments and materialized child lanes.
136    Start(AgentFanoutStartArgs),
137}
138
139#[derive(Clone, Debug, clap::Args)]
140pub struct AgentServeArgs {
141    /// Override the default socket path (`<heddle_dir>/sockets/grpc.sock`).
142    #[arg(long)]
143    pub socket: Option<PathBuf>,
144}
heddle_cli_args/cli/cli_args/commands_agent.rs

heddle_cli_args/cli/cli_args/
commands_agent.rs
