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