cli/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, transaction, 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, AgentReadyArgs, AgentReleaseArgs, AgentReserveArgs, AgentTaskCreateArgs,
21    AgentTaskListArgs, AgentTaskShowArgs, AgentTaskUpdateArgs,
22};
23
24#[derive(Clone, Debug, Subcommand)]
25pub enum AgentCommands {
26    /// Run the local agent gRPC daemon.
27    ///
28    /// The daemon binds a Unix socket inside the repo's `.heddle/sockets/`
29    /// directory and serves local same-user CLI calls.
30    Serve(AgentServeArgs),
31
32    /// Report whether the local agent daemon is running for this repo.
33    Status,
34
35    /// Ask the running daemon to drain and exit.
36    Stop,
37
38    // --- Reservation API (orchestration surface) ----------------
39    // The variants below are the stable JSON API that orchestrators
40    // (Claude Code subagents, codex harnesses, etc.) call to
41    // coordinate parallel writers on the same repo. Distinct from
42    // the daemon-control variants above: these are one-shot CLI
43    // calls that mutate the repo's `.heddle/agents/` registry.
44    /// Atomically reserve a thread for one writer.
45    Reserve(AgentReserveArgs),
46
47    /// Update reservation heartbeat.
48    Heartbeat(AgentHeartbeatArgs),
49
50    /// Capture under a session-validated reservation.
51    Capture(AgentCaptureArgs),
52
53    /// Mark a reservation's thread ready for integration.
54    Ready(AgentReadyArgs),
55
56    /// Release a reservation (status: complete | abandoned).
57    Release(AgentReleaseArgs),
58
59    /// List agent reservations (optionally filtered to alive ones).
60    List(AgentApiListArgs),
61
62    /// Manage local agent task assignments.
63    #[command(subcommand)]
64    Task(AgentTaskCommands),
65
66    /// Plan and start native fan-out lanes.
67    #[command(subcommand)]
68    Fanout(AgentFanoutCommands),
69}
70
71#[derive(Clone, Debug, Subcommand)]
72pub enum AgentTaskCommands {
73    /// Create a local agent task assignment.
74    Create(AgentTaskCreateArgs),
75
76    /// List local agent task assignments.
77    List(AgentTaskListArgs),
78
79    /// Show one local agent task assignment.
80    Show(AgentTaskShowArgs),
81
82    /// Update one local agent task assignment.
83    Update(AgentTaskUpdateArgs),
84}
85
86#[derive(Clone, Debug, Subcommand)]
87pub enum AgentFanoutCommands {
88    /// Preview fan-out lane setup and return commands without writing.
89    Plan(AgentFanoutPlanArgs),
90
91    /// Create task assignments and materialized child lanes.
92    Start(AgentFanoutStartArgs),
93}
94
95#[derive(Clone, Debug, clap::Args)]
96pub struct AgentServeArgs {
97    /// Override the default socket path (`<heddle_dir>/sockets/grpc.sock`).
98    #[arg(long)]
99    pub socket: Option<PathBuf>,
100    /// Run in the foreground; without this the daemon detaches and writes
101    /// its pidfile so the parent shell returns immediately.
102    #[arg(long)]
103    pub foreground: bool,
104}
cli/cli/cli_args/commands_agent.rs

cli/cli/cli_args/
commands_agent.rs
