blomios/IdeaSDK
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fdcf16c38762b278581b397f5c833bae7576f214
IdeaSDK/crates/application/src/agent/lifecycle.rs
Blomios fdcf16c387 chore(wip): checkpoint P8/C avant chantier Codex inter-agents 
Sauvegarde de l'arbre de travail en cours (persistance P8, conversations
C-series, write-portal frontend, médiation d'entrée) avant d'attaquer le
support de la délégation inter-agents pour les profils Codex.

Le round-trip inter-agent question/réponse est couvert sans tokens par
les tests loopback existants (state::mcp_e2e_loopback_tests).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-13 21:42:53 +02:00

2673 lines
117 KiB
Rust
Raw Blame History

//! Agent lifecycle use cases (ARCHITECTURE §6, L6).
//!
//! These own the *project-agent* side (distinct from the profile side in
//! [`super::usecases`]): creating agents and their `.md` contexts under
//! `.ideai/`, listing/reading/updating them, and — the centrepiece —
//! [`LaunchAgent`], which resolves the agent's profile + context, applies the
//! profile's context-injection strategy, opens a PTY cell at the right `cwd` and
//! spawns the CLI.
//!
//! Every use case talks **only to ports** ([`AgentContextStore`], [`ProfileStore`],
//! [`AgentRuntime`], [`PtyPort`], [`FileSystem`], [`EventBus`]); none knows about
//! a concrete adapter or Tauri.
use std::sync::Arc;
use domain::ports::{
AgentContextStore, AgentRuntime, AgentSessionFactory, ContextInjectionPlan, EventBus,
FileSystem, FsError, IdGenerator, MemoryQuery, MemoryRecall, PreparedContext, ProfileStore,
ProjectStore, PtyPort, RemotePath, SessionPlan, SkillStore, SpawnSpec, StoreError,
};
use domain::{
Agent, AgentId, AgentManifest, AgentOrigin, AgentProfile, ContextInjection, ConversationId,
ConversationParty, DomainEvent, Handoff, HandoffStore, ManifestEntry, MarkdownDoc,
MemoryIndexEntry, MemoryType, NodeId, ProfileId, Project, ProjectPath, ProviderSessionStore,
PtySize, SessionId, SessionKind, SessionStatus, Skill, TerminalSession,
};
use crate::error::AppError;
use crate::layout::{persist_doc, resolve_doc};
use crate::project::project_context_path;
use crate::terminal::{StructuredSessions, TerminalSessions};
/// Directory (relative to `.ideai/`) under which agent contexts are written.
const AGENTS_SUBDIR: &str = "agents";
/// Token budget of the project-memory recall injected into the convention file at
/// agent activation (ARCHITECTURE §14.5.4). Bounds the number of index entries
/// (étage 1) handed to the agent. Internal and intentionally **not yet exposed in
/// config**: it may later become a per-project setting without changing the
/// contract.
pub const AGENT_MEMORY_RECALL_BUDGET: usize = 2_048;
/// Fournit le [`HandoffStore`] **lié au project root** du lancement en cours (lot P7).
///
/// [`LaunchAgent`] est une **instance unique partagée par tous les projets** (le
/// project root arrive *par lancement* via [`LaunchAgentInput::project`]), alors que
/// le handoff conversationnel est **par project root**
/// (`<root>/.ideai/conversations/`, comme la mémoire et le log). Les adapters `Fs*`
/// fixent leur racine **à la construction** et ne portent pas le root par appel : on
/// ne peut donc pas figer un `HandoffStore` global. Ce **port** lève la tension —
/// calqué sur [`crate::RecordTurnProvider`] — en matérialisant un store ciblant le
/// **bon** dossier à chaque résolution (les adapters `Fs*` ne font que des jointures
/// de chemin, leur construction est triviale).
///
/// `None` ⇒ aucune injection de reprise (best-effort absente) : zéro régression pour
/// les call sites/tests qui ne le branchent pas. Implémenté dans `app-tauri` (seul
/// détenteur des adapters `Fs*`).
pub trait HandoffProvider: Send + Sync {
/// Construit le [`HandoffStore`] dont la persistance cible `root`. Appelé une fois
/// par lancement best-effort ; `None` ⇒ on saute silencieusement l'injection.
fn handoff_store_for(&self, root: &ProjectPath) -> Option<Arc<dyn HandoffStore>>;
}
/// Fournit le [`ProviderSessionStore`] **lié au project root** du lancement en cours
/// (lot P8b). Jumeau stateless de [`HandoffProvider`] : même tension (instance
/// [`LaunchAgent`] partagée vs adapter `Fs*` à racine fixée à la construction),
/// même réponse (matérialiser le store ciblant le **bon** dossier à chaque appel).
///
/// Sert à ranger, après un lancement structuré, l'id de session **moteur**
/// (resumable du provider) sous la clé de paire IdeA dans `providers.json`. `None`
/// ⇒ aucune écriture (best-effort absente) : zéro régression pour les call
/// sites/tests qui ne le branchent pas. Implémenté dans `app-tauri`.
pub trait ProviderSessionProvider: Send + Sync {
/// Construit le [`ProviderSessionStore`] dont la persistance cible `root`. Appelé
/// une fois par lancement best-effort ; `None` ⇒ on saute silencieusement
/// l'écriture du resumable.
fn provider_session_store_for(
&self,
root: &ProjectPath,
) -> Option<Arc<dyn ProviderSessionStore>>;
}
// ---------------------------------------------------------------------------
// CreateAgentFromScratch
// ---------------------------------------------------------------------------
/// Input for [`CreateAgentFromScratch::execute`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CreateAgentInput {
/// The project that owns the agent.
pub project: Project,
/// Display name of the agent.
pub name: String,
/// Runtime profile the agent launches with.
pub profile_id: ProfileId,
/// Initial `.md` content (empty when `None`).
pub initial_content: Option<String>,
}
/// Output of [`CreateAgentFromScratch::execute`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CreateAgentOutput {
/// The freshly-created agent.
pub agent: Agent,
}
/// Creates a project agent from scratch: mints an id, derives a unique `.md`
/// path, records the manifest entry, then writes the (possibly empty) context.
pub struct CreateAgentFromScratch {
contexts: Arc<dyn AgentContextStore>,
ids: Arc<dyn domain::ports::IdGenerator>,
events: Arc<dyn EventBus>,
}
impl CreateAgentFromScratch {
/// Builds the use case from its injected ports.
#[must_use]
pub fn new(
contexts: Arc<dyn AgentContextStore>,
ids: Arc<dyn domain::ports::IdGenerator>,
events: Arc<dyn EventBus>,
) -> Self {
Self {
contexts,
ids,
events,
}
}
/// Executes creation.
///
/// Ordering matters: the manifest entry is persisted **before** the context
/// is written, because [`AgentContextStore::write_context`] resolves the
/// on-disk path from the manifest.
///
/// # Errors
/// - [`AppError::Invalid`] if the name is empty or the manifest would become
/// inconsistent,
/// - [`AppError::Store`] on persistence failure.
pub async fn execute(&self, input: CreateAgentInput) -> Result<CreateAgentOutput, AppError> {
let manifest = self.contexts.load_manifest(&input.project).await?;
let id = AgentId::from_uuid(self.ids.new_uuid());
let md_path = unique_md_path(&input.name, &manifest);
let agent = Agent::new(
id,
input.name,
md_path,
input.profile_id,
AgentOrigin::Scratch,
false,
)
.map_err(|e| AppError::Invalid(e.to_string()))?;
// Append the entry and re-validate the whole manifest (unique md_paths).
let mut entries = manifest.entries;
entries.push(ManifestEntry::from_agent(&agent));
let manifest = AgentManifest::new(manifest.version, entries)
.map_err(|e| AppError::Invalid(e.to_string()))?;
self.contexts
.save_manifest(&input.project, &manifest)
.await?;
// Now the path resolves: write the initial context.
let md = MarkdownDoc::new(input.initial_content.unwrap_or_default());
self.contexts
.write_context(&input.project, &agent.id, &md)
.await?;
self.events.publish(DomainEvent::LayoutChanged {
project_id: input.project.id,
});
Ok(CreateAgentOutput { agent })
}
}
// ---------------------------------------------------------------------------
// ListAgents
// ---------------------------------------------------------------------------
/// Input for [`ListAgents::execute`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ListAgentsInput {
/// The project whose agents to list.
pub project: Project,
}
/// Output of [`ListAgents::execute`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ListAgentsOutput {
/// The project's agents (reconstructed from the manifest).
pub agents: Vec<Agent>,
}
/// Lists a project's agents by reconstructing them from the manifest entries.
pub struct ListAgents {
contexts: Arc<dyn AgentContextStore>,
}
impl ListAgents {
/// Builds the use case from the [`AgentContextStore`] port.
#[must_use]
pub fn new(contexts: Arc<dyn AgentContextStore>) -> Self {
Self { contexts }
}
/// Loads the manifest and folds each entry back into an [`Agent`].
///
/// # Errors
/// - [`AppError::Store`] on persistence failure,
/// - [`AppError::Invalid`] if a persisted entry violates an agent invariant.
pub async fn execute(&self, input: ListAgentsInput) -> Result<ListAgentsOutput, AppError> {
let manifest = self.contexts.load_manifest(&input.project).await?;
let agents = manifest
.entries
.iter()
.map(|e| {
e.to_agent()
.map_err(|err| AppError::Invalid(err.to_string()))
})
.collect::<Result<Vec<_>, _>>()?;
Ok(ListAgentsOutput { agents })
}
}
// ---------------------------------------------------------------------------
// ReadAgentContext / UpdateAgentContext
// ---------------------------------------------------------------------------
/// Input for [`ReadAgentContext::execute`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ReadAgentContextInput {
/// The owning project.
pub project: Project,
/// The agent whose `.md` to read.
pub agent_id: AgentId,
}
/// Output of [`ReadAgentContext::execute`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ReadAgentContextOutput {
/// The agent's Markdown context.
pub content: MarkdownDoc,
}
/// Reads an agent's `.md` context.
pub struct ReadAgentContext {
contexts: Arc<dyn AgentContextStore>,
}
impl ReadAgentContext {
/// Builds the use case.
#[must_use]
pub fn new(contexts: Arc<dyn AgentContextStore>) -> Self {
Self { contexts }
}
/// Reads the context.
///
/// # Errors
/// - [`AppError::NotFound`] if the agent (or its `.md`) is unknown,
/// - [`AppError::Store`] on persistence failure.
pub async fn execute(
&self,
input: ReadAgentContextInput,
) -> Result<ReadAgentContextOutput, AppError> {
let content = self
.contexts
.read_context(&input.project, &input.agent_id)
.await?;
Ok(ReadAgentContextOutput { content })
}
}
/// Input for [`UpdateAgentContext::execute`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UpdateAgentContextInput {
/// The owning project.
pub project: Project,
/// The agent whose `.md` to overwrite.
pub agent_id: AgentId,
/// New Markdown content.
pub content: String,
}
/// Overwrites an agent's `.md` context.
pub struct UpdateAgentContext {
contexts: Arc<dyn AgentContextStore>,
}
impl UpdateAgentContext {
/// Builds the use case.
#[must_use]
pub fn new(contexts: Arc<dyn AgentContextStore>) -> Self {
Self { contexts }
}
/// Writes the new context.
///
/// # Errors
/// - [`AppError::NotFound`] if the agent is unknown,
/// - [`AppError::Store`] on persistence failure.
pub async fn execute(&self, input: UpdateAgentContextInput) -> Result<(), AppError> {
let md = MarkdownDoc::new(input.content);
self.contexts
.write_context(&input.project, &input.agent_id, &md)
.await?;
Ok(())
}
}
// ---------------------------------------------------------------------------
// ChangeAgentProfile
// ---------------------------------------------------------------------------
/// Input for [`ChangeAgentProfile::execute`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ChangeAgentProfileInput {
/// The owning project.
pub project: Project,
/// The agent whose runtime profile to hot-swap.
pub agent_id: AgentId,
/// The new runtime profile.
pub profile_id: ProfileId,
/// Terminal height in rows for a possible hot relaunch.
pub rows: u16,
/// Terminal width in columns for a possible hot relaunch.
pub cols: u16,
}
/// Output of [`ChangeAgentProfile::execute`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ChangeAgentProfileOutput {
/// The mutated agent (now carrying the new profile).
pub agent: Agent,
/// The freshly relaunched session, when a live session was hot-swapped.
pub relaunched: Option<TerminalSession>,
}
/// Hot-swaps an existing agent's runtime profile (ARCHITECTURE §15.1).
///
/// **Single Responsibility**: mutate the profile in the manifest, clear the now
/// foreign conversation id on every persisted layout cell hosting the agent, and
/// — if the agent is live — kill its PTY and re-sequence the session in the same
/// cell with the new engine. The relaunch is **composed**, not duplicated: this
/// use case *calls* [`LaunchAgent::execute`] rather than re-implementing the spawn.
///
/// Ports consumed (ISP — only what is needed): [`AgentContextStore`] (manifest),
/// [`ProfileStore`] (validate the target profile), [`ProjectStore`] +
/// [`FileSystem`] (clean the conversation id on persisted layouts, exactly like
/// [`crate::layout::SnapshotRunningAgents`]), [`TerminalSessions`] + [`PtyPort`]
/// (detect/kill a live session), an [`Arc<LaunchAgent>`] for the hot relaunch, and
/// [`EventBus`] to publish.
pub struct ChangeAgentProfile {
contexts: Arc<dyn AgentContextStore>,
profiles: Arc<dyn ProfileStore>,
projects: Arc<dyn ProjectStore>,
fs: Arc<dyn FileSystem>,
sessions: Arc<TerminalSessions>,
pty: Arc<dyn PtyPort>,
launch: Arc<LaunchAgent>,
events: Arc<dyn EventBus>,
/// Registre des sessions **structurées** (§17.5), pour un « kill » polymorphe
/// (§17.4) : si l'agent a une session structurée vivante, on la `shutdown()` au
/// lieu de tuer un PTY. Injecté au câblage via [`Self::with_structured`] ; `None`
/// ⇒ seul le registre PTY est consulté (mode legacy / tests existants).
structured: Option<Arc<StructuredSessions>>,
}
impl ChangeAgentProfile {
/// Builds the use case from its injected ports (and the composed launcher).
#[must_use]
#[allow(clippy::too_many_arguments)]
pub fn new(
contexts: Arc<dyn AgentContextStore>,
profiles: Arc<dyn ProfileStore>,
projects: Arc<dyn ProjectStore>,
fs: Arc<dyn FileSystem>,
sessions: Arc<TerminalSessions>,
pty: Arc<dyn PtyPort>,
launch: Arc<LaunchAgent>,
events: Arc<dyn EventBus>,
) -> Self {
Self {
contexts,
profiles,
projects,
fs,
sessions,
pty,
launch,
events,
structured: None,
}
}
/// Branche le registre des sessions **structurées** (§17.4) pour un kill
/// polymorphe au hot-swap. Builder additif : signature de [`Self::new`]
/// **inchangée** (les tests A existants restent verts), le câblage fait
/// `ChangeAgentProfile::new(...).with_structured(registry)`.
#[must_use]
pub fn with_structured(mut self, structured: Arc<StructuredSessions>) -> Self {
self.structured = Some(structured);
self
}
/// Executes the hot-swap, following the 7-step algorithm of §15.1.
///
/// # Errors
/// - [`AppError::NotFound`] if the agent or the target profile is unknown,
/// - [`AppError::Invalid`] on a manifest/layout invariant violation,
/// - [`AppError::Store`] / [`AppError::FileSystem`] / [`AppError::Process`] on
/// the respective port failures (manifest, layouts, PTY kill, relaunch).
pub async fn execute(
&self,
input: ChangeAgentProfileInput,
) -> Result<ChangeAgentProfileOutput, AppError> {
// 1. Load the manifest and resolve the agent's entry (NotFound otherwise).
let manifest = self.contexts.load_manifest(&input.project).await?;
let entry = manifest
.entries
.iter()
.find(|e| e.agent_id == input.agent_id)
.ok_or_else(|| AppError::NotFound(format!("agent {}", input.agent_id)))?;
// 2. Same profile ⇒ no-op: return the agent unchanged, no kill/relaunch,
// no event.
if entry.profile_id == input.profile_id {
let agent = entry
.to_agent()
.map_err(|e| AppError::Invalid(e.to_string()))?;
return Ok(ChangeAgentProfileOutput {
agent,
relaunched: None,
});
}
// 3. Validate that the target profile is a known one (ProfileStore.list).
let known = self
.profiles
.list()
.await?
.into_iter()
.any(|p| p.id == input.profile_id);
if !known {
return Err(AppError::NotFound(format!("profile {}", input.profile_id)));
}
// 4. Mutate the entry (new profile), re-validate (to_agent + manifest)
// and persist.
let mut entries = manifest.entries;
let mut mutated_agent = None;
for e in &mut entries {
if e.agent_id == input.agent_id {
e.profile_id = input.profile_id;
let agent = e
.to_agent()
.map_err(|err| AppError::Invalid(err.to_string()))?;
mutated_agent = Some(agent);
}
}
let agent =
mutated_agent.ok_or_else(|| AppError::NotFound(format!("agent {}", input.agent_id)))?;
let manifest = AgentManifest::new(manifest.version, entries)
.map_err(|e| AppError::Invalid(e.to_string()))?;
self.contexts
.save_manifest(&input.project, &manifest)
.await?;
// 5. Invalidate the engine link on every persisted layout: for each leaf
// hosting this agent, drop the (now foreign) engine resumable cache and
// reset the running flag, while **preserving** the stable IdeA pair id.
// Mirrors `SnapshotRunningAgents`: resolve_doc → walk agent_leaves →
// mutate → persist_doc (if changed). Returns the preserved pair id.
let pair_id = self
.invalidate_engine_link(&input.project, &input.agent_id)
.await?;
// 6. A live session? Kill its PTY then relaunch in the same cell with the
// new profile, carrying the **preserved** pair id (so the handoff is
// re-injected and resume routes via providers.json[new provider]).
let relaunched = self.relaunch_if_live(&input, pair_id).await?;
// 7. Publish the profile change and return.
self.events.publish(DomainEvent::AgentProfileChanged {
agent_id: input.agent_id,
profile_id: input.profile_id,
});
Ok(ChangeAgentProfileOutput { agent, relaunched })
}
/// Invalidates the **engine link** on every persisted layout leaf hosting
/// `agent_id` (step 5), while **preserving** the IdeA pair conversation id.
///
/// Post-P8a, `LeafCell::conversation_id` is a stable, provider-independent
/// **pair id** (User↔agent) that retrieves the work log + handoff and must
/// survive a profile swap. Only the engine-side cache
/// (`LeafCell::engine_session_id`, a foreign resumable for the new engine) is
/// cleared; the source of truth for resume routing is `providers.json`. The
/// running flag is reset too.
///
/// Returns the **preserved pair id** of the agent (the first non-`None` leaf;
/// every leaf of this agent carries the same User↔agent pair id), or `None`
/// when no hosting leaf was found. Persists only when something actually
/// changed (a project with no such leaf is a no-op write).
async fn invalidate_engine_link(
&self,
project: &Project,
agent_id: &AgentId,
) -> Result<Option<String>, AppError> {
let project = self.projects.load_project(project.id).await?;
let mut doc = resolve_doc(self.fs.as_ref(), &project).await?;
let mut changed = false;
let mut pair_id: Option<String> = None;
for named in &mut doc.layouts {
for (leaf_id, leaf_agent) in named.tree.agent_leaves() {
if &leaf_agent != agent_id {
continue;
}
// Capture the preserved pair id (stable across all leaves of this
// agent) — used to relaunch with handoff re-injection (P7).
if pair_id.is_none() {
if let Some(cid) = named
.tree
.leaf(leaf_id)
.and_then(|l| l.conversation_id.clone())
{
pair_id = Some(cid);
}
}
// Pure ops — only NodeNotFound is possible, which cannot happen
// since `leaf_id` came from this very tree.
//
// Preserve `conversation_id` (stable pair id); only drop the
// engine-side resumable cache (foreign to the new engine).
named.tree = named
.tree
.set_cell_engine_session(leaf_id, None)
.map_err(|e| AppError::Invalid(e.to_string()))?;
named.tree = named
.tree
.set_agent_running(leaf_id, false)
.map_err(|e| AppError::Invalid(e.to_string()))?;
changed = true;
}
}
if changed {
persist_doc(self.fs.as_ref(), &project, &doc).await?;
}
Ok(pair_id)
}
/// Kills the agent's live PTY (if any) and relaunches it in the same cell with
/// the new profile (step 6), composing [`LaunchAgent::execute`]. Returns the
/// relaunched session, or `None` when the agent had no live session.
///
/// `pair_id` is the **preserved** IdeA pair id (User↔agent) captured at step 5;
/// it is threaded into the relaunch so the handoff (P7) is re-injected into the
/// new engine and resume (P8c) is routed via `providers.json[new provider]` —
/// the old engine's resumable is **never** replayed (providers.json for the new
/// provider is empty ⇒ `SessionPlan::None`, fidelity carried by the handoff).
/// When step 5 found no hosting leaf (e.g. a background session without a cell),
/// the id is **derived** deterministically via `for_pair(User, agent)`.
async fn relaunch_if_live(
&self,
input: &ChangeAgentProfileInput,
pair_id: Option<String>,
) -> Result<Option<TerminalSession>, AppError> {
// Résolution **polymorphe** de la session vivante sur les deux registres
// (§17.4) : structuré d'abord, puis PTY. Un agent ne vit que dans un seul des
// deux à la fois (invariant « 1 session/agent »).
let killed = self.kill_live_session(&input.agent_id).await?;
let Some(node_id) = killed else {
// Aucune session vivante (ni structurée, ni PTY) ⇒ rien à relancer.
return Ok(None);
};
// Pair id préservé (step 5) ; en repli (session de fond sans cellule), on
// dérive l'id de paire déterministe User↔agent — les cellules sont toujours
// User↔agent, donc cette dérivation coïncide avec ce qu'eût porté la feuille.
let conversation_id = Some(pair_id.unwrap_or_else(|| {
ConversationId::for_pair(
ConversationParty::User,
ConversationParty::agent(input.agent_id),
)
.to_string()
}));
let output = self
.launch
.execute(LaunchAgentInput {
project: input.project.clone(),
agent_id: input.agent_id,
rows: input.rows,
cols: input.cols,
node_id,
// Pair id **préservé** (id de paire IdeA stable) : le handoff (P7) est
// réinjecté dans le nouveau moteur, et le resume (P8c) est routé via
// providers.json[nouveau provider] — l'ancien resumable n'est jamais
// repassé (providers.json du nouveau provider vide ⇒ moteur neuf).
conversation_id,
// Internal relaunch (no app-tauri composition root in scope) ⇒ the
// MCP runtime is not injected here; `apply_mcp_config` falls back to
// the minimal declaration. A profile-hot-swap that needs the real
// endpoint is re-driven through the app-tauri launch path.
mcp_runtime: None,
})
.await?;
Ok(Some(output.session))
}
/// Tue la session vivante de `agent_id` de façon **polymorphe** (§17.4) :
/// `shutdown()` si elle est structurée, kill PTY sinon. Retire la session de son
/// registre **avant** l'arrêt, pour que la garde d'unicité du relance (sur les
/// deux registres) ne voie plus de session vivante.
///
/// Retourne `Some(node_id_hôte)` quand une session a été tuée (le node où
/// relancer), `None` si l'agent n'avait aucune session vivante. La cellule hôte
/// peut elle-même être absente (session de fond) ⇒ `Some(None)` est replié sur un
/// node neuf côté relance via `LaunchAgentInput.node_id = None`.
async fn kill_live_session(
&self,
agent_id: &AgentId,
) -> Result<Option<Option<NodeId>>, AppError> {
// 1. Session structurée vivante ? ⇒ shutdown polymorphe.
if let Some(structured) = &self.structured {
if let Some(session_id) = structured.session_id_for_agent(agent_id) {
let node_id = structured.node_for_agent(agent_id);
if let Some(session) = structured.remove(&session_id) {
session
.shutdown()
.await
.map_err(|e| AppError::Process(e.to_string()))?;
}
return Ok(Some(node_id));
}
}
// 2. Sinon, session PTY vivante ? ⇒ kill PTY (chemin historique).
let Some(session_id) = self.sessions.session_for_agent(agent_id) else {
return Ok(None);
};
let node_id = self.sessions.node_for_agent(agent_id);
if let Some(handle) = self.sessions.remove(&session_id) {
self.pty.kill(&handle).await?;
}
Ok(Some(node_id))
}
}
// ---------------------------------------------------------------------------
// DeleteAgent
// ---------------------------------------------------------------------------
/// Input for [`DeleteAgent::execute`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DeleteAgentInput {
/// The owning project.
pub project: Project,
/// The agent to remove.
pub agent_id: AgentId,
}
/// Removes an agent from the project manifest.
///
/// The orphaned `.md` file is left on disk: the [`FileSystem`] port exposes no
/// delete, and keeping the file is the safe default (the user may want to recover
/// the context). Re-creating an agent with the same name reuses a fresh path.
pub struct DeleteAgent {
contexts: Arc<dyn AgentContextStore>,
events: Arc<dyn EventBus>,
}
impl DeleteAgent {
/// Builds the use case.
#[must_use]
pub fn new(contexts: Arc<dyn AgentContextStore>, events: Arc<dyn EventBus>) -> Self {
Self { contexts, events }
}
/// Drops the manifest entry for the agent.
///
/// # Errors
/// - [`AppError::NotFound`] if the agent is not in the manifest,
/// - [`AppError::Store`] on persistence failure.
pub async fn execute(&self, input: DeleteAgentInput) -> Result<(), AppError> {
let manifest = self.contexts.load_manifest(&input.project).await?;
let before = manifest.entries.len();
let entries: Vec<ManifestEntry> = manifest
.entries
.into_iter()
.filter(|e| e.agent_id != input.agent_id)
.collect();
if entries.len() == before {
return Err(AppError::NotFound(format!("agent {}", input.agent_id)));
}
let manifest = AgentManifest::new(manifest.version, entries)
.map_err(|e| AppError::Invalid(e.to_string()))?;
self.contexts
.save_manifest(&input.project, &manifest)
.await?;
self.events.publish(DomainEvent::LayoutChanged {
project_id: input.project.id,
});
Ok(())
}
}
// ---------------------------------------------------------------------------
// LaunchAgent
// ---------------------------------------------------------------------------
/// Input for [`LaunchAgent::execute`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LaunchAgentInput {
/// The owning project.
pub project: Project,
/// The agent to launch.
pub agent_id: AgentId,
/// Initial terminal height in rows.
pub rows: u16,
/// Initial terminal width in columns.
pub cols: u16,
/// The layout leaf hosting the session (a fresh node when `None`).
pub node_id: Option<NodeId>,
/// The persistent CLI conversation id currently recorded on the hosting cell,
/// if any. `Some` means a previous conversation exists and the launch should
/// **resume** it; `None` means a fresh cell (the launch may *assign* a new id
/// when the profile supports it). The caller (which owns the layout) reads this
/// from the leaf's [`domain::layout::LeafCell::conversation_id`].
pub conversation_id: Option<String>,
/// Runtime facts needed to write the **real** IdeA MCP server declaration
/// (M5d). These are **OS/runtime data** (the IdeA executable path, the
/// project's loopback endpoint) that live in `app-tauri` — they are *injected
/// as data* from the composition root, never computed in `application` (which
/// must not depend on `app-tauri`, cadrage v5 §0.3 / §7).
///
/// `None` ⇒ no runtime injected (launches issued from inside `application`:
/// the orchestrator's `spawn_agent`/`ask_agent`, a profile hot-swap relaunch,
/// or tests). In that case [`apply_mcp_config`](LaunchAgent::apply_mcp_config)
/// still honours the profile's `McpConfigStrategy`, but falls back to a
/// **coherent minimal** declaration (the `idea mcp-server` command without the
/// endpoint/project/requester args) rather than a project-bound one — see
/// [`mcp_server_declaration`].
pub mcp_runtime: Option<McpRuntime>,
}
/// OS/runtime facts injected by the composition root (`app-tauri`) to materialise
/// the **real** IdeA MCP server declaration in an agent's `.mcp.json` (cadrage v5
/// §2). Carrying these as **plain data** on [`LaunchAgentInput`] keeps
/// `application` free of any `app-tauri` / `current_exe` / `mcp_endpoint`
/// dependency: the endpoint stays computed by the *single source of truth*
/// (`app-tauri::mcp_endpoint`) and only its **string** crosses the layer boundary.
///
/// All four fields are the exact strings the spawned bridge expects on its command
/// line (`<exe> mcp-server --endpoint <endpoint> --project <project_id> --requester
/// <requester>`); the `project_id` must already be in the **hyphen-free 32-hex
/// `simple` form** consumed by the M5c handshake guard (`serve_peer`).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct McpRuntime {
/// Absolute path to the IdeA executable (`std::env::current_exe()`), used as the
/// declaration's `command` — the CLI spawns *this* binary in its `mcp-server`
/// bridge mode.
pub exe: String,
/// The project's loopback endpoint string (`mcp_endpoint(project).as_cli_arg()`),
/// passed as `--endpoint`. **Same source of truth** as the listener bound by
/// `ensure_mcp_server` (cadrage v5 §2 coherence invariant).
pub endpoint: String,
/// The project id in the **hyphen-free 32-hex `simple` form** consumed by the
/// M5c handshake guard, passed as `--project`.
pub project_id: String,
/// The launching agent's id, passed as `--requester` so the server tags
/// `OrchestratorRequestProcessed.requester_id` with the real agent (cadrage v5
/// §1.4) instead of the frozen `"mcp"` placeholder.
pub requester: String,
}
/// Descripteur d'une session **structurée** (IA, cellule chat) démarrée par
/// [`LaunchAgent`] (ARCHITECTURE §17.4). Renvoyé en plus du snapshot
/// [`TerminalSession`] quand le profil porte un `structured_adapter` : il identifie
/// la session structurée vivante (registre [`StructuredSessions`]) sans faire fuiter
/// l'`Arc<dyn AgentSession>` à travers la frontière de sortie du use case.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct StructuredSessionDescriptor {
/// L'id de session IdeA de la session structurée (clé du registre).
pub session_id: SessionId,
/// L'agent IA pilotant cette session.
pub agent_id: AgentId,
/// La cellule (feuille de layout) qui héberge la vue chat.
pub node_id: NodeId,
/// L'id de conversation du moteur, s'il a déjà été attribué.
pub conversation_id: Option<String>,
}
/// Output of [`LaunchAgent::execute`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LaunchAgentOutput {
/// The created agent terminal session.
///
/// **Toujours présent**, y compris pour un agent IA structuré (cellule chat) :
/// dans ce cas c'est un snapshot `kind = Agent` portant l'id de la session
/// structurée (cf. [`Self::structured`]), conformément à §17.4. Garde la sortie
/// **non cassante** pour A/B et le câblage existant.
pub session: TerminalSession,
/// L'**id de paire IdeA** (pivot **logique** de la conversation, ARCHITECTURE
/// §19.7) assigné par ce lancement, quand la cellule n'en portait pas encore. Le
/// caller le persiste sur la feuille hôte via `set_cell_conversation` : c'est la
/// clé qui retrouve **log + handoff** au (re)lancement (P7) et survit au swap de
/// profil. **Ce n'est plus l'id de session moteur** (qui part désormais dans
/// [`Self::engine_session_id`]). `None` quand rien de neuf n'a été assigné (reprise
/// d'un id existant, mode dégradé, ou profil sans session) — rien à persister.
pub assigned_conversation_id: Option<String>,
/// L'**id de session moteur** (resumable du provider : id Claude `--resume`, ou
/// l'UUID minté pour `--session-id`) exposé/attribué par ce lancement, **distinct**
/// de l'id de paire (ARCHITECTURE §19.7, lot P8a). Le caller le range dans le
/// **cache** `LeafCell::engine_session_id` (via `set_cell_engine_session`) — jamais
/// sur `conversation_id`. La **source de vérité** du resumable reste `providers.json`
/// (lot P8b, hors P8a). `None` pour le chemin PTY/legacy ou quand le moteur n'expose
/// aucun id : rien à cacher.
pub engine_session_id: Option<String>,
/// Descripteur de la session **structurée**, présent **uniquement** quand ce
/// lancement a routé vers un agent IA structuré (`profile.structured_adapter =
/// Some(_)`, ARCHITECTURE §17.4). `None` pour le chemin PTY/terminal brut
/// historique. Champ **additionnel et optionnel** : la sortie reste compatible
/// avec les use cases A/B et le câblage qui ne lisent que `session` /
/// `assigned_conversation_id`.
pub structured: Option<StructuredSessionDescriptor>,
}
/// Launches an agent: resolve profile + context, prepare the invocation, apply
/// the context-injection plan, open a PTY at the resolved `cwd`, spawn the CLI.
///
/// This is the orchestrating use case of L6 and therefore consumes several ports
/// — each only for the slice it needs (Interface Segregation): the context store
/// (agent `.md` + manifest), the profile store (resolve the runtime), the runtime
/// (build the [`SpawnSpec`]), the filesystem (materialise a `conventionFile`
/// context), and the PTY (spawn + optional stdin injection).
pub struct LaunchAgent {
contexts: Arc<dyn AgentContextStore>,
profiles: Arc<dyn ProfileStore>,
runtime: Arc<dyn AgentRuntime>,
fs: Arc<dyn FileSystem>,
pty: Arc<dyn PtyPort>,
skills: Arc<dyn SkillStore>,
sessions: Arc<TerminalSessions>,
events: Arc<dyn EventBus>,
ids: Arc<dyn IdGenerator>,
/// Bounded recall of the project's memory index, injected into the convention
/// file at activation (ARCHITECTURE §14.5.4). Best-effort by contract: an absent
/// or empty memory yields an empty list, never blocking a launch.
recall: Arc<dyn MemoryRecall>,
/// Optional contextual embedder-suggestion check (LOT C3, §14.5.5), run
/// best-effort right after the memory recall at activation — the moment an agent
/// reads the project memory. `None` keeps the launcher independent of it (legacy
/// wiring / tests). A failure here never affects the launch.
embedder_suggestion: Option<Arc<crate::embedder::CheckEmbedderSuggestion>>,
/// Fabrique des sessions **structurées** (IA, §17). Injectée au câblage
/// (composition root) via [`Self::with_structured`]. `None` ⇒ le routage §17.4
/// est désactivé et **tout** profil suit le chemin PTY historique (mode legacy /
/// tests existants, qui restent verts sans changement de signature).
session_factory: Option<Arc<dyn AgentSessionFactory>>,
/// Registre des sessions structurées vivantes (§17.5), jumeau de
/// [`TerminalSessions`]. Peuplé quand un agent IA structuré est lancé. `None` en
/// même temps que [`Self::session_factory`].
structured: Option<Arc<StructuredSessions>>,
/// Provider du [`HandoffStore`] **par project root** (lot P7), pour réinjecter
/// **best-effort** le résumé de reprise (`summary_md` + objectif) de la
/// conversation de la cellule dans le convention file au (re)lancement. Injecté au
/// câblage via [`Self::with_handoff_provider`] ; `None` ⇒ aucune injection de
/// reprise (zéro régression pour les call sites/tests legacy). Un handoff
/// absent/illisible ⇒ lancement normal, jamais d'échec.
handoffs: Option<Arc<dyn HandoffProvider>>,
/// Provider du [`ProviderSessionStore`] **par project root** (lot P8b), pour ranger
/// **best-effort** l'id de session moteur (resumable du provider) sous la clé de
/// paire IdeA dans `providers.json` après un lancement structuré. Injecté au câblage
/// via [`Self::with_provider_session_provider`] ; `None` ⇒ aucune écriture (zéro
/// régression pour les call sites/tests legacy). Une écriture en échec ⇒ lancement
/// normal, jamais d'échec.
provider_sessions: Option<Arc<dyn ProviderSessionProvider>>,
}
impl LaunchAgent {
/// Builds the use case from its injected ports.
#[must_use]
#[allow(clippy::too_many_arguments)]
pub fn new(
contexts: Arc<dyn AgentContextStore>,
profiles: Arc<dyn ProfileStore>,
runtime: Arc<dyn AgentRuntime>,
fs: Arc<dyn FileSystem>,
pty: Arc<dyn PtyPort>,
skills: Arc<dyn SkillStore>,
sessions: Arc<TerminalSessions>,
events: Arc<dyn EventBus>,
ids: Arc<dyn IdGenerator>,
recall: Arc<dyn MemoryRecall>,
embedder_suggestion: Option<Arc<crate::embedder::CheckEmbedderSuggestion>>,
) -> Self {
Self {
contexts,
profiles,
runtime,
fs,
pty,
skills,
sessions,
events,
ids,
recall,
embedder_suggestion,
session_factory: None,
structured: None,
handoffs: None,
provider_sessions: None,
}
}
/// Branche le provider de **store de sessions provider (lot P8b)** sur ce launcher :
/// après un lancement structuré exposant un id de session moteur, range
/// `(pair_conversation_id, provider_key) → engine_session_id` dans `providers.json`
/// du projet. Sans cet appel (cas legacy / tests existants), aucune écriture —
/// signature de [`Self::new`] **inchangée**, donc aucun appelant existant ne casse.
///
/// Builder additif (consomme `self`, retourne `Self`) : le câblage fait
/// `LaunchAgent::new(...).with_provider_session_provider(provider)`.
#[must_use]
pub fn with_provider_session_provider(
mut self,
provider_sessions: Arc<dyn ProviderSessionProvider>,
) -> Self {
self.provider_sessions = Some(provider_sessions);
self
}
/// Branche le provider de **handoff de reprise (lot P7)** sur ce launcher : au
/// (re)lancement, si la cellule porte une `conversation_id` et qu'un [`Handoff`]
/// existe pour elle, son `summary_md` (et son objectif) sont injectés comme section
/// de contexte dans le convention file, à côté de la mémoire projet. Sans cet appel
/// (cas legacy / tests existants), aucune section de reprise n'est injectée —
/// signature de [`Self::new`] **inchangée**, donc aucun appelant existant ne casse.
///
/// Builder additif (consomme `self`, retourne `Self`) : le câblage fait
/// `LaunchAgent::new(...).with_handoff_provider(provider)`.
#[must_use]
pub fn with_handoff_provider(mut self, handoffs: Arc<dyn HandoffProvider>) -> Self {
self.handoffs = Some(handoffs);
self
}
/// Branche le **routage structuré (§17.4)** sur ce launcher : fournit la fabrique
/// [`AgentSessionFactory`] et le registre [`StructuredSessions`] injectés au
/// composition root. Sans cet appel (cas legacy / tests existants), `execute`
/// route **tout** vers le PTY — signature de [`Self::new`] **inchangée**, donc
/// aucun appelant existant ne casse.
///
/// Builder (consomme `self`, retourne `Self`) pour rester additif : le câblage
/// fait `LaunchAgent::new(...).with_structured(factory, registry)`.
#[must_use]
pub fn with_structured(
mut self,
session_factory: Arc<dyn AgentSessionFactory>,
structured: Arc<StructuredSessions>,
) -> Self {
self.session_factory = Some(session_factory);
self.structured = Some(structured);
self
}
/// Resolves the Markdown bodies of an agent's assigned skills, in the
/// **manifest order** (deterministic). A skill that no longer exists in its
/// store (deleted out from under the assignment) is silently skipped — a
/// dangling [`domain::SkillRef`] must not block a launch.
///
/// # Errors
/// [`AppError::Store`] on any store failure other than a missing skill.
async fn resolve_skills(
&self,
agent: &Agent,
root: &ProjectPath,
) -> Result<Vec<Skill>, AppError> {
let mut out = Vec::with_capacity(agent.skills.len());
for skill_ref in &agent.skills {
match self
.skills
.get(skill_ref.scope, root, skill_ref.skill_id)
.await
{
Ok(skill) => out.push(skill),
Err(StoreError::NotFound) => {}
Err(e) => return Err(e.into()),
}
}
Ok(out)
}
/// Resolves the project's memory recall (index/hooks) to inject into the
/// convention file at activation (ARCHITECTURE §14.5.4), mirroring
/// [`Self::resolve_skills`]. The query text is the agent's persona `.md`
/// (irrelevant to the naïve adapter, but already the right query for the future
/// semantic recall — zero refactor at étage 2), bounded by
/// [`AGENT_MEMORY_RECALL_BUDGET`].
///
/// **Best-effort, never blocking**: an absent or empty memory yields an empty
/// list by the [`MemoryRecall`] contract, and any unexpected error degrades to
/// an empty list rather than failing the launch (exactly like a dangling skill).
async fn resolve_memory(&self, root: &ProjectPath, persona: &str) -> Vec<MemoryIndexEntry> {
let query = MemoryQuery {
text: persona.to_owned(),
token_budget: AGENT_MEMORY_RECALL_BUDGET,
};
self.recall.recall(root, &query).await.unwrap_or_default()
}
/// Résout **best-effort** le handoff de reprise de la cellule (lot P7), calqué sur
/// [`Self::resolve_memory`]. L'injection n'a lieu que si :
/// - la cellule porte une `conversation_id` ([`LaunchAgentInput::conversation_id`]),
/// - le provider de handoff est câblé ([`Self::with_handoff_provider`]),
/// - cette chaîne se parse en [`ConversationId`] (UUID), et
/// - un [`Handoff`] existe effectivement pour cette conversation.
///
/// **Jamais bloquant** : un parse en échec, l'absence de provider/handoff, ou
/// toute erreur du store dégradent vers `None` (pas de section de reprise), exactly
/// comme une mémoire absente — un lancement n'est jamais cassé par la reprise.
async fn resolve_handoff(
&self,
root: &ProjectPath,
cell_conversation_id: Option<&str>,
) -> Option<Handoff> {
let provider = self.handoffs.as_ref()?;
let raw = cell_conversation_id?;
// Le `conversation_id` d'une cellule est un identifiant de paire (UUID, §C3).
// Un id non-UUID (ancien id CLI, donnée corrompue) ⇒ pas d'injection.
let conversation = ConversationId::from_uuid(uuid::Uuid::parse_str(raw).ok()?);
let store = provider.handoff_store_for(root)?;
// Toute erreur de lecture/désérialisation ⇒ pas d'injection (best-effort).
store.load(conversation).await.ok().flatten()
}
/// Reads the shared project context from `.ideai/CONTEXT.md`.
///
/// A missing file is normal for existing projects and simply omits the
/// project-context section from the generated model context.
async fn resolve_project_context(&self, project: &Project) -> Result<String, AppError> {
match self.fs.read(&project_context_path(project)).await {
Ok(bytes) => String::from_utf8(bytes)
.map_err(|e| AppError::Store(format!("project context is not UTF-8: {e}"))),
Err(FsError::NotFound(_)) => Ok(String::new()),
Err(e) => Err(AppError::FileSystem(e.to_string())),
}
}
/// Executes the launch.
///
/// Step order is contractually significant (and unit-tested): resolve the
/// agent + context, **`prepare_invocation`**, **apply the injection plan**
/// (write a `conventionFile` / set an env var), then **`pty.spawn`** at the
/// resolved `cwd`, and finally pipe the context on stdin for the `Stdin`
/// strategy.
///
/// # Errors
/// - [`AppError::NotFound`] if the agent or its profile is unknown,
/// - [`AppError::Invalid`] for a zero-sized terminal,
/// - [`AppError::Store`] / [`AppError::FileSystem`] / [`AppError::Process`] on
/// the respective port failures.
pub async fn execute(&self, input: LaunchAgentInput) -> Result<LaunchAgentOutput, AppError> {
let size =
PtySize::new(input.rows, input.cols).map_err(|e| AppError::Invalid(e.to_string()))?;
// 1. Resolve the agent from the manifest (name + profile + md_path).
let manifest = self.contexts.load_manifest(&input.project).await?;
let entry = manifest
.entries
.iter()
.find(|e| e.agent_id == input.agent_id)
.ok_or_else(|| AppError::NotFound(format!("agent {}", input.agent_id)))?;
let agent = entry
.to_agent()
.map_err(|e| AppError::Invalid(e.to_string()))?;
// 1b. Enforce the "one live session per agent" invariant (decision: an
// agent is a singleton that runs in a single cell at a time). This
// runs AFTER the NotFound resolution above (so an unknown agent still
// errors NotFound) but BEFORE any I/O (run dir, seed, spawn). If the
// agent already owns a live session:
// - with a requested node → rebind the live session to that cell and
// return it without respawning;
// - without a requested node → idempotent background/no-op launch:
// return the existing session without respawning.
// The resume path (agent dead ⇒ no live session) is unaffected.
//
// Invariant « 1 session vivante/agent » **généralisé aux deux registres**
// (§17.4) : un agent est vivant s'il a une session PTY *ou* structurée.
// On consulte d'abord le registre PTY (chemin historique), puis le
// registre structuré (le cas échéant).
//
// R0a — discrimination réattache-de-vue vs second lancement (cadrage v5
// §3.2, Trou A). Un agent est un **singleton** : une seule session vivante.
// Quand l'agent est déjà vivant, on distingue (cf. [`Self::reattach_decision`]) :
// - **réattache de vue** (rebind sans respawn) : le `node_id` demandé est
// le node hôte vivant, OU la cellule porte une `conversation_id`
// (réattache explicite — la cellule sait que l'agent tournait) ;
// - **lancement background/idempotent** : ni node, ni conversation ⇒ no-op
// (rend la session existante, pas de respawn) ;
// - **second lancement neuf** : on vise un **autre** node, sans signal de
// réattache ⇒ refus [`AppError::AgentAlreadyRunning`] (node hôte rapporté).
if let Some(existing_id) = self.sessions.session_for_agent(&input.agent_id) {
let host_node = self.sessions.node_for_agent(&input.agent_id);
match reattach_decision(input.node_id, host_node, input.conversation_id.as_deref()) {
ReattachDecision::Rebind { node_id } => {
if let Some(session) = self.sessions.rebind_agent_node(&input.agent_id, node_id)
{
return Ok(LaunchAgentOutput {
session,
assigned_conversation_id: None,
engine_session_id: None,
structured: None,
});
}
}
ReattachDecision::Idempotent => {}
ReattachDecision::Refuse { node_id } => {
return Err(AppError::AgentAlreadyRunning {
agent_id: input.agent_id,
node_id,
});
}
}
// Idempotent (or a rebind that found no entry to move) — hand back the
// already-registered session, no respawn, nothing new to persist.
if let Some(session) = self.sessions.session(&existing_id) {
return Ok(LaunchAgentOutput {
session,
assigned_conversation_id: None,
engine_session_id: None,
structured: None,
});
}
}
// Garde structurée (§17.4) : même sémantique côté registre IA. R0a appliqué de
// façon identique — rebind de la cellule-vue pour une réattache légitime,
// idempotence sans node/conversation, refus d'un second lancement neuf ailleurs.
if let Some(structured) = &self.structured {
if let Some(existing) = structured.session_for_agent(&input.agent_id) {
let host_node = structured.node_for_agent(&input.agent_id);
let node_id = match reattach_decision(
input.node_id,
host_node,
input.conversation_id.as_deref(),
) {
ReattachDecision::Rebind { node_id } => {
let _ = structured.rebind_agent_node(&input.agent_id, node_id);
node_id
}
// Idempotent — garder le node hôte courant, sinon un node neuf.
ReattachDecision::Idempotent => host_node.unwrap_or_else(NodeId::new_random),
ReattachDecision::Refuse { node_id } => {
return Err(AppError::AgentAlreadyRunning {
agent_id: input.agent_id,
node_id,
});
}
};
return Ok(LaunchAgentOutput {
session: structured_snapshot(&existing, input.agent_id, node_id, size),
assigned_conversation_id: None,
// Rebind de vue : aucune (ré)assignation ⇒ rien de neuf à cacher.
engine_session_id: None,
structured: Some(StructuredSessionDescriptor {
session_id: existing.id(),
agent_id: input.agent_id,
node_id,
conversation_id: existing.conversation_id(),
}),
});
}
}
// 2. Read its context and resolve its profile.
let content = self
.contexts
.read_context(&input.project, &agent.id)
.await?;
let profile = self
.profiles
.list()
.await?
.into_iter()
.find(|p| p.id == agent.profile_id)
.ok_or_else(|| AppError::NotFound(format!("profile {} for agent", agent.profile_id)))?;
// 3. Compute and create the agent's isolated run directory
// `<root>/.ideai/run/<agent-id>/` (ARCHITECTURE §14.1). The PTY cwd is
// *never* the project root: each agent gets its own directory so that N
// instances of the same profile never collide on a single conventional
// file (CLAUDE.md, …). This is the only I/O in the cwd resolution; the
// runtime's `prepare_invocation` stays pure.
let run_dir = agent_run_dir(&input.project.root, &agent.id)
.map_err(|e| AppError::Invalid(e.to_string()))?;
self.fs
.create_dir_all(&RemotePath::new(run_dir.as_str().to_owned()))
.await?;
// 3b. Seed the CLI's permission config in the run dir so the agent runs
// with the project's full autonomy and never blocks on per-command
// permission prompts. The agent's cwd is the run dir, so the CLI
// writes/reads its permission file there; without a seed, the CLI
// accumulates narrow per-command approvals and keeps prompting.
// Pragmatic per-CLI seed pending the universal `.ideai/permissions.json`
// + OS-sandbox model. Non-clobbering and best-effort.
self.seed_cli_permissions(&profile, &run_dir, &input.project.root)
.await?;
// 4. Prepare the invocation (pure): command + args + injection plan + cwd.
// The run dir is passed as the cwd base; the profile's `{agentRunDir}`
// placeholder resolves against it.
let prepared = PreparedContext {
content: content.clone(),
relative_path: agent.context_path.clone(),
};
// 4a. Resolve the session intention (T4). The conversation id is a property
// of the *cell*, not the PTY: the caller (which owns the layout) passes
// the cell's current `conversation_id`. Any id this launch *assigns* is
// returned in the output so the caller persists it on the leaf.
let (session_plan, assigned_conversation_id) = self
.resolve_session_plan(&profile, input.conversation_id.clone(), &input.project.root)
.await;
let mut spec =
self.runtime
.prepare_invocation(&profile, &prepared, &run_dir, &session_plan)?;
// 5. Resolve the agent's assigned skills (their `.md` bodies), then apply
// the injection plan side effects *before* spawning.
let skills = self.resolve_skills(&agent, &input.project.root).await?;
let project_context = self.resolve_project_context(&input.project).await?;
let memory = self
.resolve_memory(&input.project.root, content.as_str())
.await;
// Reprise conversationnelle (lot P7) : best-effort, additif. Si la cellule a une
// conversation et qu'un handoff existe, son résumé est injecté dans le convention
// file (à côté de la mémoire projet). Indépendant du provider/resumable id.
let handoff = self
.resolve_handoff(&input.project.root, input.conversation_id.as_deref())
.await;
// Best-effort contextual embedder suggestion (LOT C3, §14.5.5): the agent
// has just read the project memory, so this is the moment to check whether a
// semantic embedder would now help. Fully isolated from the launch outcome —
// an error or absence of the check never affects activation.
if let Some(check) = &self.embedder_suggestion {
let _ = check
.execute(crate::embedder::CheckEmbedderSuggestionInput {
project_id: input.project.id,
project_root: input.project.root.clone(),
})
.await;
}
self.apply_injection(
&input.project,
&agent.context_path,
&content,
&project_context,
&skills,
&memory,
handoff.as_ref(),
profile.mcp.is_some(),
&mut spec,
)
.await?;
// 5a. ── INJECTION DE LA CONF MCP (cadrage v3, Décision 3) ──
// Strictement APRÈS le convention file (étape 5) et AVANT le spawn /
// `factory.start` (étapes 5b/6). Si le profil porte une `McpCapability`,
// IdeA matérialise SA config MCP au format de CETTE CLI, dans le **même**
// run dir isolé que le convention file et le seed de permissions. `None`
// ⇒ aucun write/flag/env (chemin actuel inchangé, zéro régression).
self.apply_mcp_config(&profile, &run_dir, input.mcp_runtime.as_ref(), &mut spec)
.await;
// 5b. ── POINT DE ROUTAGE §17.4 : IA structuré vs terminal brut ──
// Le convention file (CLAUDE.md / AGENTS.md) vient d'être écrit dans le
// run dir (étape 5) ; la CLI structurée le lira à chaque tour
// (incarnation « un run par tour »). Si le profil porte un
// `structured_adapter` ET que la fabrique structurée est câblée, on
// démarre une `AgentSession` via le port — **pas** de `pty.spawn` — et on
// l'enregistre dans `StructuredSessions`. Sinon : chemin PTY inchangé.
if let (Some(factory), Some(structured), true) = (
self.session_factory.as_ref(),
self.structured.as_ref(),
profile.structured_adapter.is_some(),
) {
// ── Clé **logique** de la cellule = id de paire IdeA (ARCHITECTURE §19.7,
// lot P8a) ──
// - cellule porteuse d'un `conversation_id` (resume, ou lancement délégué
// qui a déjà injecté l'id de paire A↔B) ⇒ c'est **déjà** l'id de paire,
// on le conserve tel quel ;
// - cellule structurée **neuve** (lancement direct utilisateur, aucun
// requester) ⇒ on **dérive** `pair(User, agent)` via la fonction domaine
// pure partagée avec `resolve_conversation` (aucun couplage à
// l'orchestrateur). C'est cet id — et **non** l'id de session moteur —
// qui retrouve log + handoff au (re)lancement (P7) et survit au swap.
let pair_conversation_id = input.conversation_id.clone().unwrap_or_else(|| {
ConversationId::for_pair(
ConversationParty::User,
ConversationParty::agent(agent.id),
)
.to_string()
});
return self
.launch_structured(
factory.as_ref(),
structured,
&agent,
&profile,
&prepared,
&run_dir,
&session_plan,
pair_conversation_id,
&input.project.root,
input.node_id,
size,
)
.await;
}
// 6. Spawn the PTY at the resolved cwd; adopt its session id everywhere.
let handle = self.pty.spawn(spec.clone(), size).await?;
let session_id = handle.session_id;
// 7. For the Stdin strategy, pipe the context once the PTY is live.
if matches!(spec.context_plan, Some(ContextInjectionPlan::Stdin)) {
self.pty.write(&handle, content.as_str().as_bytes())?;
}
let node_id = input.node_id.unwrap_or_else(NodeId::new_random);
let mut session = TerminalSession::starting(
session_id,
node_id,
spec.cwd.clone(),
SessionKind::Agent { agent_id: agent.id },
size,
);
session.status = SessionStatus::Running;
self.sessions.insert(handle, session.clone());
self.events.publish(DomainEvent::AgentLaunched {
agent_id: agent.id,
session_id,
});
Ok(LaunchAgentOutput {
session,
assigned_conversation_id,
// Chemin PTY/terminal brut : pas de session moteur structurée à cacher.
engine_session_id: None,
structured: None,
})
}
/// Démarre un agent IA **structuré** (§17.4) : crée une [`AgentSession`] via la
/// fabrique, l'enregistre dans [`StructuredSessions`] avec son `agent_id`/`node_id`
/// et publie [`DomainEvent::AgentLaunched`]. **Aucun `pty.spawn`** — la cellule est
/// de type chat.
///
/// L'`assigned_conversation_id` calculé en amont (`resolve_session_plan`) est
/// préservé, mais l'id réellement attribué par le moteur (s'il diffère ou s'il
/// apparaît seulement après le démarrage) prime quand il est disponible : c'est
/// `session.conversation_id()` qui fait foi pour la persistance sur la cellule.
#[allow(clippy::too_many_arguments)]
async fn launch_structured(
&self,
factory: &dyn AgentSessionFactory,
structured: &Arc<StructuredSessions>,
agent: &Agent,
profile: &AgentProfile,
prepared: &PreparedContext,
run_dir: &ProjectPath,
session_plan: &SessionPlan,
pair_conversation_id: String,
root: &ProjectPath,
node_id: Option<NodeId>,
size: PtySize,
) -> Result<LaunchAgentOutput, AppError> {
let session = factory
.start(profile, prepared, run_dir, session_plan)
.await
.map_err(|e| AppError::Process(e.to_string()))?;
let session_id = session.id();
let node_id = node_id.unwrap_or_else(NodeId::new_random);
// Enregistre la session vivante (invariant « 1 session/agent » : déjà gardé en
// amont sur les deux registres).
structured.insert(Arc::clone(&session), agent.id, node_id);
// ── SÉPARATION DES DEUX CLÉS (ARCHITECTURE §19.7, lot P8a) ──
// - **id de paire** (`pair_conversation_id`) : clé **logique** persistée sur
// `LeafCell.conversation_id`. C'est lui qui retrouve log + handoff (P7) et
// survit au swap. Stable, indépendant du provider.
// - **id de session moteur** (`session.conversation_id()`) : resumable du
// provider (Claude/Codex). Rangé **séparément** dans le cache
// `LeafCell.engine_session_id` (via `set_cell_engine_session`) — **jamais**
// sur `conversation_id`. `None` si le moteur n'expose encore aucun id.
let engine_session_id = session.conversation_id();
// ── P8b — range le resumable moteur par provider dans `providers.json`
// (best-effort, jamais bloquant) ──
// On persiste `(pair_conversation_id, provider_key) → engine_session_id`
// **uniquement** quand le moteur expose un id ET que le provider est câblé.
// La clé provider est dérivée de la **famille de moteur** (`structured_adapter`),
// pas de l'uuid d'instance du profil : un swap vers la même famille réutilise la
// même entrée. Toute défaillance (provider absent, pair_conversation_id non-UUID,
// erreur du store) dégrade silencieusement — un lancement n'est **jamais** cassé
// par cette persistance (lot P8c lira ce store pour `--resume`).
if let Some(engine_id) = engine_session_id.as_deref() {
self.persist_provider_session(root, profile, &pair_conversation_id, engine_id)
.await;
}
let snapshot = structured_snapshot(&session, agent.id, node_id, size);
self.events.publish(DomainEvent::AgentLaunched {
agent_id: agent.id,
session_id,
});
Ok(LaunchAgentOutput {
session: snapshot,
// Cellule ⇐ id de **paire** (pivot logique de reprise §15.2 / §19.7).
assigned_conversation_id: Some(pair_conversation_id),
// Cache moteur ⇐ id resumable du provider (distinct de la paire).
engine_session_id: engine_session_id.clone(),
structured: Some(StructuredSessionDescriptor {
session_id,
agent_id: agent.id,
node_id,
conversation_id: engine_session_id,
}),
})
}
/// Range **best-effort** (lot P8b) le resumable moteur `engine_id` sous la clé
/// `(pair_conversation_id, provider_key)` dans `providers.json` du projet.
///
/// `provider_key` est dérivée de la **famille de moteur** du profil
/// ([`StructuredAdapter::provider_key`]) ; un profil sans `structured_adapter` (ne
/// devrait pas arriver sur ce chemin structuré) ⇒ skip. `pair_conversation_id` est
/// une chaîne : un id non-UUID (donnée legacy/corrompue) ⇒ skip. Le provider absent
/// ([`Self::with_provider_session_provider`] non appelé) ⇒ skip. Toute erreur du
/// store est tracée et avalée : **jamais** d'échec ni de panique — le lancement a
/// déjà réussi à ce stade.
async fn persist_provider_session(
&self,
root: &ProjectPath,
profile: &AgentProfile,
pair_conversation_id: &str,
engine_id: &str,
) {
let Some(provider) = self.provider_sessions.as_ref() else {
return;
};
let Some(adapter) = profile.structured_adapter else {
return;
};
// Le `conversation_id` d'une cellule est un id de paire (UUID, §C3).
let Ok(uuid) = uuid::Uuid::parse_str(pair_conversation_id) else {
return;
};
let conversation = ConversationId::from_uuid(uuid);
let Some(store) = provider.provider_session_store_for(root) else {
return;
};
// Best-effort : toute erreur du store est avalée — le lancement a déjà réussi,
// la persistance du resumable ne doit jamais le casser (lot P8c lira ce store).
let _ = store
.set(conversation, adapter.provider_key(), engine_id)
.await;
}
/// Resolves the [`SessionPlan`] for a launch from the profile's session
/// strategy and the cell's current `conversation_id` (T4).
///
/// Returns the plan *and* — when this launch mints a fresh id — that id, so the
/// caller can persist it on the hosting leaf. The id is only generated for an
/// `Assign` (profile has a `session` block with an `assign_flag`, and the cell
/// had no id yet); every other branch returns `None` (nothing to persist).
///
/// Branches:
/// - cell already has an id ⇒ [`SessionPlan::Resume`] (reopen) — no new id;
/// - no id, profile has `session.assign_flag` ⇒ mint a UUID, [`SessionPlan::Assign`];
/// - no id, profile has `session` but no `assign_flag` (degraded) ⇒
/// [`SessionPlan::None`] (nothing to resume on a first launch; the adapter
/// uses the bare resume flag only on later reopens);
/// - profile without a `session` block ⇒ [`SessionPlan::None`] (legacy).
async fn resolve_session_plan(
&self,
profile: &AgentProfile,
cell_conversation_id: Option<String>,
root: &ProjectPath,
) -> (SessionPlan, Option<String>) {
// Profil **structuré** (§17, lot P8c) : le `conversation_id` de la cellule est
// un **id de paire IdeA**, jamais le resumable du moteur. Le passer en `--resume`
// serait invalide (Claude/Codex attendent *leur* id). On route donc le resume
// moteur via `providers.json`, keyé par `(id de paire, provider_key)` (écrit en
// P8b). Rien à pré-attribuer ici : l'id de paire est géré en aval (P8a), le
// resumable moteur est capté/rapporté par P8b au fil de l'exécution.
if let Some(adapter) = profile.structured_adapter {
// Store câblé : on lit le resumable moteur rangé pour cette paire+provider.
if let Some(provider) = self.provider_sessions.as_ref() {
let engine = match &cell_conversation_id {
// L'id de paire (UUID) → resumable moteur via providers.json.
Some(raw) => match uuid::Uuid::parse_str(raw) {
Ok(uuid) => match provider.provider_session_store_for(root) {
Some(store) => store
.get(ConversationId::from_uuid(uuid), adapter.provider_key())
.await
.ok()
.flatten(),
None => None,
},
Err(_) => None,
},
None => None,
};
return match engine {
// Vrai resumable moteur connu ⇒ resume propre du moteur.
Some(engine_id) => (
SessionPlan::Resume {
conversation_id: engine_id,
},
None,
),
// Aucun resumable (None / parse KO / store absent / pas d'id de
// cellule) ⇒ premier lancement propre. Le moteur attribuera/rapportera
// son id (capté par P8b) ; la continuité du travail est assurée par le
// handoff (P7). On ne passe **jamais** l'id de paire en `--resume`.
None => (SessionPlan::None, None),
};
}
// Store **non câblé** (tests/legacy) : repli gracieux sur l'ancien
// comportement — une conversation sur la cellule ⇒ `Resume`, sinon `None`.
// Garantit zéro régression des tests qui ne câblent pas le store.
return match cell_conversation_id {
Some(conversation_id) => (SessionPlan::Resume { conversation_id }, None),
None => (SessionPlan::None, None),
};
}
// Profils **non structurés** (PTY/TUI) : la cellule porte toujours l'id moteur.
// Comportement **inchangé** depuis T4.
let Some(session) = &profile.session else {
return (SessionPlan::None, None);
};
// The cell already carries a conversation: resume it (no new id minted).
if let Some(conversation_id) = cell_conversation_id {
return (SessionPlan::Resume { conversation_id }, None);
}
// Fresh cell. Only mint+assign an id when the profile can assign one;
// otherwise (degraded mode) the first launch has nothing to resume.
if session.assign_flag.is_some() {
let conversation_id = self.ids.new_uuid().to_string();
(
SessionPlan::Assign {
conversation_id: conversation_id.clone(),
},
Some(conversation_id),
)
} else {
(SessionPlan::None, None)
}
}
/// Seeds the agent's run dir with the CLI permission config matching its
/// context-injection convention, so the agent inherits the project's autonomy
/// instead of prompting per command.
///
/// Conditioned on the CLI convention (only Claude Code — convention file
/// `CLAUDE.md` — has a known seed today); a no-op for any other CLI.
/// Best-effort and **non-clobbering**: an existing file (possibly user-edited)
/// is left untouched.
///
/// # Errors
/// [`AppError::FileSystem`] if the directory/file cannot be written.
async fn seed_cli_permissions(
&self,
profile: &AgentProfile,
run_dir: &ProjectPath,
project_root: &ProjectPath,
) -> Result<(), AppError> {
let is_claude = matches!(
&profile.context_injection,
ContextInjection::ConventionFile { target }
if target
.rsplit(['/', '\\'])
.next()
.unwrap_or(target)
.eq_ignore_ascii_case("CLAUDE.md")
);
if !is_claude {
return Ok(());
}
let settings_path =
RemotePath::new(format!("{}/.claude/settings.local.json", run_dir.as_str()));
if self.fs.exists(&settings_path).await? {
return Ok(());
}
self.fs
.create_dir_all(&RemotePath::new(format!("{}/.claude", run_dir.as_str())))
.await?;
self.fs
.write(
&settings_path,
claude_settings_seed(project_root.as_str()).as_bytes(),
)
.await?;
Ok(())
}
/// Applies the context-injection plan that must happen *before* spawn:
/// materialising a `conventionFile` context (write the `.md` to `<cwd>/target`)
/// or attaching the on-disk context path to an environment variable. `Args` is
/// already folded into the spec by the runtime; `Stdin` is handled post-spawn.
#[allow(clippy::too_many_arguments)]
async fn apply_injection(
&self,
project: &Project,
context_rel_path: &str,
content: &MarkdownDoc,
project_context: &str,
skills: &[Skill],
memory: &[MemoryIndexEntry],
handoff: Option<&Handoff>,
mcp_enabled: bool,
spec: &mut SpawnSpec,
) -> Result<(), AppError> {
match spec.context_plan.clone() {
Some(ContextInjectionPlan::File { target }) => {
// conventionFile (ARCHITECTURE §14.1): IdeA *generates* the
// conventional file (e.g. CLAUDE.md) inside the agent's isolated
// run directory — `spec.cwd` is that run dir, never the project
// root, so there is zero collision between agents. The document is
// composed: an absolute project-root header (so the agent knows
// where to operate, since its cwd is *not* the root), the agent's
// persona `.md`, then the bodies of its assigned skills (§14.2).
let document = compose_convention_file(
project.root.as_str(),
project_context,
content.as_str(),
skills,
memory,
handoff,
mcp_enabled,
);
let path = RemotePath::new(join(&spec.cwd, &target));
self.fs.write(&path, document.as_bytes()).await?;
}
Some(ContextInjectionPlan::Env { var }) => {
// Hand the CLI the absolute path of the agent's `.md` (which lives at
// `<root>/.ideai/<context_rel_path>`) via the environment variable.
let abspath = join(&project.root, &format!(".ideai/{context_rel_path}"));
spec.env.push((var, abspath));
}
// Args were folded into spec.args by prepare_invocation; Stdin is
// applied after the PTY is live.
Some(ContextInjectionPlan::Args { .. }) | Some(ContextInjectionPlan::Stdin) | None => {}
}
Ok(())
}
/// Materialises the IdeA MCP server config for **this** CLI when the profile
/// carries an [`McpCapability`] (cadrage v3, Décision 3). Runs **after** the
/// convention file (`apply_injection`) and **before** the spawn / `factory.start`,
/// in the **same** isolated run dir as the convention file and the permission seed.
///
/// Dispatch by [`McpConfigStrategy`]:
/// - `ConfigFile { target }` → write `<run_dir>/<target>` (e.g. `.mcp.json`) with
/// the IdeA MCP server declaration. **Best-effort** (any write/exists failure is
/// swallowed so it **never** fails the launch), with two clobber regimes:
/// * with an injected [`McpRuntime`] (real app-tauri launch) the file is
/// **regenerated and clobbered on every (re)launch**, exactly like the
/// convention file. The declaration's `command` carries the **stable** IdeA
/// exe path (`$APPIMAGE`) and the project's live endpoint — both drift between
/// runs (the AppImage mount path changes at each remount/reboot), so a stale
/// `.mcp.json` would point the bridge at a dead binary/socket. `.mcp.json` is
/// IdeA-managed (not user-edited), so clobbering is safe;
/// * without a runtime (orchestrator / hot-swap / tests) only a degraded minimal
/// declaration is available, so the write stays **non-clobbering** (mirrors
/// [`Self::seed_cli_permissions`]) — never overwriting a real declaration.
/// - `Flag { flag }` → append the flag + run-dir config path to [`SpawnSpec::args`].
/// - `Env { var }` → append the variable (run-dir config path) to [`SpawnSpec::env`].
///
/// `profile.mcp == None` ⇒ no-op: no write, no flag, no env (current path, zero
/// regression).
///
/// MCP runtime (M5d): when the composition root injects a [`McpRuntime`], the
/// declaration written for a `ConfigFile` strategy is the **real** one — it points
/// the spawned `idea mcp-server` bridge at the project's exact loopback endpoint
/// (same source of truth as `ensure_mcp_server`, cadrage v5 §2). When no runtime is
/// injected (launches issued from inside `application`), a coherent **minimal**
/// declaration is written instead (see [`mcp_server_declaration`]). `Flag`/`Env`
/// are unaffected by the runtime: they keep passing the run-dir config path.
async fn apply_mcp_config(
&self,
profile: &AgentProfile,
run_dir: &ProjectPath,
runtime: Option<&McpRuntime>,
spec: &mut SpawnSpec,
) {
let Some(mcp) = &profile.mcp else {
return;
};
match &mcp.config {
domain::profile::McpConfigStrategy::ConfigFile { target } => {
let path = RemotePath::new(join(run_dir, target));
let declaration = mcp_server_declaration(mcp.transport, runtime);
match runtime {
// Real launch (app-tauri injected the runtime): the declaration
// carries the **stable** IdeA executable path (`$APPIMAGE`, resolved
// by `idea_exe_path`) and the project's live loopback endpoint. Both
// can drift between runs — the AppImage internal mount path changes
// at every remount/reboot — so the file MUST be regenerated and
// **clobbered** on every (re)launch, exactly like the convention file
// (`apply_injection`). `.mcp.json` is IdeA-managed, not user-edited,
// so there is nothing to preserve. Best-effort: a write failure must
// never fail the launch.
Some(_) => {
let _ = self.fs.write(&path, declaration.as_bytes()).await;
}
// Internal launch (orchestrator / hot-swap / tests): we only have a
// degraded **minimal** declaration (no endpoint/project/requester).
// Stay non-clobbering — mirrors `seed_cli_permissions` — so we never
// overwrite a real declaration previously written by an app-tauri
// launch with the minimal one.
None => match self.fs.exists(&path).await {
Ok(true) => {}
Ok(false) => {
let _ = self.fs.write(&path, declaration.as_bytes()).await;
}
Err(_) => {}
},
}
}
domain::profile::McpConfigStrategy::Flag { flag } => {
// Pass the server via a launch flag (e.g. `--mcp-config {path}`). The
// config path is the run dir itself (the CLI's cwd), where the server
// declaration / connection is anchored.
spec.args.push(flag.clone());
spec.args.push(run_dir.as_str().to_owned());
}
domain::profile::McpConfigStrategy::Env { var } => {
spec.env.push((var.clone(), run_dir.as_str().to_owned()));
}
}
}
}
/// Outcome of the R0a discrimination between a legitimate **view reattach** and a
/// **fresh second launch** of an already-live agent (cadrage v5 §3.2, Trou A).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum ReattachDecision {
/// Rebind the live session's view to `node_id` without respawning (the request
/// targets the live host node, or carries an explicit reattach signal).
Rebind { node_id: NodeId },
/// Background / idempotent no-op: hand back the existing session unchanged
/// (neither a node nor a conversation id was supplied).
Idempotent,
/// Refuse the launch — a genuine second launch of a singleton agent already
/// live on `node_id` (the host node, reported in `AgentAlreadyRunning`).
Refuse { node_id: NodeId },
}
impl ReattachDecision {
/// Decides reattach vs refuse for an already-live agent. See [`reattach_decision`].
#[must_use]
pub(crate) fn resolve(
requested_node: Option<NodeId>,
host_node: Option<NodeId>,
conversation_id: Option<&str>,
) -> Self {
reattach_decision(requested_node, host_node, conversation_id)
}
}
/// Decides whether a launch hitting an already-live agent is a legitimate view
/// **reattach** (rebind), a **background/idempotent** no-op, or a **refused** second
/// launch (cadrage v5 §3.2, Trou A). Pure (no I/O), unit-testable.
///
/// Signals (both already present in the launch flow):
/// - `requested_node` — the hosting leaf the caller targets (`None` ⇒ no cell, e.g.
/// a background launch);
/// - `host_node` — the node currently hosting the agent's live session, if known;
/// - `conversation_id` — the conversation id recorded on the hosting cell. Its
/// presence means the **cell knows the agent was running** ⇒ it is a reattach of a
/// view onto an in-progress session, not a brand-new launch.
///
/// Rules:
/// - requested node **is** the host node ⇒ `Rebind` (re-open of the same cell);
/// - a `conversation_id` is present ⇒ `Rebind` (explicit reattach, even on another
/// node — the cell is a rebindable view, §17.6);
/// - no node **and** no conversation ⇒ `Idempotent` (background/no-op relaunch);
/// - a different node, no reattach signal ⇒ `Refuse` (genuine second launch).
fn reattach_decision(
requested_node: Option<NodeId>,
host_node: Option<NodeId>,
conversation_id: Option<&str>,
) -> ReattachDecision {
// Explicit reattach: the cell carries a conversation id, so it is re-binding a
// view onto an already-running session. Rebind to the requested node, or keep the
// current host node when none was supplied.
if conversation_id.is_some() {
if let Some(node_id) = requested_node.or(host_node) {
return ReattachDecision::Rebind { node_id };
}
return ReattachDecision::Idempotent;
}
match requested_node {
// Same cell re-opened ⇒ idempotent rebind (no respawn).
Some(node) if host_node == Some(node) => ReattachDecision::Rebind { node_id: node },
// A different cell with no reattach signal ⇒ genuine second launch: refuse,
// reporting the live host node (falling back to the requested node only if the
// host is somehow unknown, so the error always carries a meaningful cell).
Some(node) => ReattachDecision::Refuse {
node_id: host_node.unwrap_or(node),
},
// No node and no reattach signal ⇒ background/idempotent no-op.
None => ReattachDecision::Idempotent,
}
}
/// Builds the IdeA MCP server declaration written into a CLI's `ConfigFile` MCP
/// config (cadrage v3 D3 ; cadrage v5 §2). Kept pure (no I/O) so it is unit-testable.
///
/// Two shapes, by whether the composition root injected a [`McpRuntime`]:
///
/// - **`Some(runtime)` — the real declaration (M5d, end of the placeholder)**:
/// `command = runtime.exe` (the IdeA executable), and `args` carry the
/// `mcp-server` subcommand plus the project's exact loopback `--endpoint`, its
/// `--project` (hyphen-free 32-hex form, consumed by the M5c guard) and the
/// launching agent as `--requester`. The endpoint string comes verbatim from the
/// **single source of truth** (`app-tauri::mcp_endpoint`), so the bridge connects
/// to exactly what `ensure_mcp_server` listens on.
///
/// - **`None` — coherent minimal declaration**: launches issued from inside
/// `application` (orchestrator/hot-swap/tests) have no OS/runtime facts to inject;
/// rather than fabricate a project-bound endpoint, we write the `idea mcp-server`
/// command without the endpoint/project/requester args. It stays a valid,
/// self-consistent `mcpServers/idea` entry (the bridge would resolve the endpoint
/// from its own project context), surfacing `transport` for the future socket path.
#[must_use]
fn mcp_server_declaration(
transport: domain::profile::McpTransport,
runtime: Option<&McpRuntime>,
) -> String {
// Common `.mcp.json`-style shape (Claude Code et CLIs apparentées). The transport
// is surfaced so a socket-based CLI can be wired later without changing this seam.
let transport_label = match transport {
domain::profile::McpTransport::Stdio => "stdio",
domain::profile::McpTransport::Socket => "socket",
};
// `command` + extra args depend on whether OS/runtime facts were injected.
// Each `args` entry is emitted as an escaped JSON string so an exe path or
// endpoint with spaces/backslashes/quotes stays valid JSON.
let (command, extra_args) = match runtime {
Some(rt) => {
let arg = |label: &str, value: &str| {
format!(
",\n {},\n {}",
json_string(label),
json_string(value)
)
};
let extra = format!(
"{}{}{}",
arg("--endpoint", &rt.endpoint),
arg("--project", &rt.project_id),
arg("--requester", &rt.requester),
);
(rt.exe.as_str(), extra)
}
None => ("idea", String::new()),
};
let command = json_string(command);
format!(
r#"{{
"mcpServers": {{
"idea": {{
"command": {command},
"args": [
"mcp-server"{extra_args}
],
"transport": "{transport_label}"
}}
}}
}}
"#
)
}
/// Wraps a string as a JSON string literal (quotes + escaping), reusing the path
/// escaper so an exe path / endpoint with spaces, backslashes or quotes stays valid
/// JSON in the generated `.mcp.json`.
fn json_string(s: &str) -> String {
format!("\"{}\"", json_escape(s))
}
/// Builds an absolute path string by joining a [`ProjectPath`] with a relative
/// segment using a POSIX separator.
fn join(base: &ProjectPath, rel: &str) -> String {
let b = base.as_str().trim_end_matches(['/', '\\']);
format!("{b}/{rel}")
}
/// Computes an agent's isolated run directory `<root>/.ideai/run/<agent-id>/`
/// (ARCHITECTURE §14.1). This is the PTY cwd for the agent — never the project
/// root — guaranteeing that two distinct agents on the same project root get two
/// distinct cwd (the anti-collision contract).
///
/// # Errors
/// Propagates [`DomainError`](domain::error::DomainError) if the joined path is
/// not a valid [`ProjectPath`] (should not happen for an absolute project root).
pub(crate) fn agent_run_dir(
root: &ProjectPath,
agent_id: &AgentId,
) -> Result<ProjectPath, domain::error::DomainError> {
ProjectPath::new(join(root, &format!(".ideai/run/{agent_id}")))
}
/// Construit le snapshot [`TerminalSession`] qui représente une session
/// **structurée** (cellule chat) dans la sortie de [`LaunchAgent`] (§17.4).
///
/// Le modèle de sortie reste le même que pour le PTY (non cassant pour A/B) : un
/// snapshot `kind = Agent` portant l'id de la session structurée. Le `cwd` n'a pas
/// de sens process ici (la cellule chat n'a pas de PTY) ; on réutilise le run dir
/// au câblage si besoin, mais le snapshot ne porte qu'un placeholder cohérent.
fn structured_snapshot(
session: &Arc<dyn domain::ports::AgentSession>,
agent_id: AgentId,
node_id: NodeId,
size: PtySize,
) -> TerminalSession {
// La cellule chat n'a pas de cwd PTY ; un chemin racine neutre suffit au snapshot
// (le run dir réel reste connu de l'adapter). `ProjectPath::new("/")` ne peut pas
// échouer (chemin absolu trivial).
let cwd = ProjectPath::new("/").expect("/ est un ProjectPath absolu valide");
let mut snapshot = TerminalSession::starting(
session.id(),
node_id,
cwd,
SessionKind::Agent { agent_id },
size,
);
snapshot.status = SessionStatus::Running;
snapshot
}
/// Builds the Claude Code permission seed (`.claude/settings.local.json`) written
/// into an agent's run dir: full project autonomy (`bypassPermissions` + broad
/// Read/Edit/Write/Bash) with the project root granted as an additional working
/// directory (the cwd is the run dir, the agent works on the root above it), while
/// keeping destructive/out-of-project commands denied. `project_root` is embedded
/// verbatim; it is JSON-escaped to stay valid for unusual paths.
///
/// Pure (no I/O), so it is unit-testable in isolation.
#[must_use]
fn claude_settings_seed(project_root: &str) -> String {
let root = json_escape(project_root);
format!(
r#"{{
"permissions": {{
"defaultMode": "bypassPermissions",
"additionalDirectories": [
"{root}"
],
"allow": [
"Read",
"Edit",
"Write",
"Bash"
],
"deny": [
"Bash(sudo *)",
"Bash(rm -rf /)",
"Bash(rm -rf /*)",
"Bash(rm -rf ~)",
"Bash(rm -rf ~/)",
"Bash(rm -rf ~/*)",
"Bash(rm -rf $HOME*)",
"Bash(mkfs*)",
"Bash(dd if=*)",
"Bash(shutdown*)",
"Bash(reboot*)"
]
}},
"skipDangerousModePermissionPrompt": true,
"enabledMcpjsonServers": ["idea"],
"sandbox": {{
"enabled": false
}}
}}
"#
)
}
/// Minimal JSON string escaper for embedding a filesystem path in the settings
/// seed (handles the characters that actually occur in paths: backslash, quote,
/// and control chars).
fn json_escape(s: &str) -> String {
let mut out = String::with_capacity(s.len());
for c in s.chars() {
match c {
'"' => out.push_str("\\\""),
'\\' => out.push_str("\\\\"),
'\n' => out.push_str("\\n"),
'\r' => out.push_str("\\r"),
'\t' => out.push_str("\\t"),
c if (c as u32) < 0x20 => out.push_str(&format!("\\u{:04x}", c as u32)),
c => out.push(c),
}
}
out
}
/// Composes the convention file IdeA writes into an agent's run directory: an
/// absolute project-root header (the agent's cwd is the run dir, *not* the root,
/// so it must be told where to work), the IdeA orchestration contract, the
/// agent's persona `.md`, then the bodies of its assigned `skills` under a
/// `# Skills` section (ARCHITECTURE §14.2).
///
/// Skills are emitted in the order given (the caller passes them in manifest
/// order, making the output deterministic); each is introduced by a `##` header
/// carrying its name. When `skills` is empty the section is omitted entirely, so
/// an agent with no skills gets exactly the previous document.
///
/// The project's `memory` recall (index/hooks, ARCHITECTURE §14.5.4) is appended as
/// a `# Mémoire projet` section — one `- [Title](slug.md) — hook (type)` line per
/// entry, in the order given. When `memory` is empty the section is omitted
/// entirely, so an agent with no memory gets exactly the previous document.
///
/// The conversation `handoff` (lot P7, ARCHITECTURE §19) is appended **last**, as a
/// `# Reprise de la conversation` section carrying the optional objective and the
/// cumulative `summary_md`. Placed after the project memory (the most situational,
/// "where we left off" context an agent reads), it is omitted entirely when `handoff`
/// is `None`, so an agent with no handoff gets exactly the previous document.
///
/// Kept as a **pure** function (no I/O) so it is unit-testable in isolation.
///
/// The orchestration prose adapts to the agent's **surface** (cadrage v3, Décision
/// 3): when `mcp_enabled` is `true` (`profile.mcp.is_some()`), the agent sees the
/// native `idea_*` tools, so the prose points to those instead of the file
/// protocol — while keeping the **same** ban on the provider's native subagents.
/// When `false` (`mcp == None`) the prose is the **current `.ideai/requests`
/// wording, unchanged** (zero regression).
#[must_use]
pub(crate) fn compose_convention_file(
project_root: &str,
project_context: &str,
agent_md: &str,
skills: &[Skill],
memory: &[MemoryIndexEntry],
handoff: Option<&Handoff>,
mcp_enabled: bool,
) -> String {
let mut out = String::new();
out.push_str("# Project root\n\n");
out.push_str(project_root);
out.push_str("\n\nTous tes travaux portent sur ce project root (chemin absolu ci-dessus). ");
out.push_str(
"Ton répertoire courant est un dossier d'exécution isolé (`.ideai/run/<agent>/`) ; \
opère sur le project root, pas sur ce dossier.\n\n",
);
out.push_str("---\n\n");
out.push_str("# Orchestration IdeA\n\n");
if mcp_enabled {
// Surface MCP (cadrage v3, D3) : l'alternative native aux subagents est
// exposée comme outils typés `idea_*`. L'interdiction des subagents natifs
// du fournisseur est **conservée** ; seule la voie de délégation change.
out.push_str(
"Pour déléguer une tâche à un autre agent, n'utilise jamais les subagents \
natifs du fournisseur IA. Utilise les outils IdeA natifs : \
`idea_ask_agent` (déléguer une tâche et recevoir la réponse), \
`idea_launch_agent` (lancer/réattacher un agent) et `idea_list_agents` \
(lister les agents du projet). IdeA lancera ou réattachera l'agent cible \
avec son propre AI Profile, son contexte et sa mémoire.\n\n",
);
// Protocole de délégation (Option 1, B-5) : côté agent SOLLICITÉ. Une tâche
// déléguée arrive dans ton terminal préfixée `[IdeA · tâche de … · ticket …]`.
// Tu DOIS y répondre via l'outil `idea_reply`, jamais en texte libre — sinon
// l'agent qui t'a sollicité reste bloqué (sa réponse ne lui parviendra pas).
out.push_str(
"Quand tu reçois une tâche déléguée par IdeA (un message préfixé \
`[IdeA · tâche de … · ticket …]`), traite-la puis appelle \
**impérativement** l'outil `idea_reply(result=…)` pour rendre ton \
résultat. Ne réponds **jamais** uniquement en texte : seul `idea_reply` \
débloque l'agent qui t'a sollicité.\n\n",
);
} else {
out.push_str(
"Pour déléguer une tâche à un autre agent, n'utilise jamais les subagents \
natifs du fournisseur IA. Écris une requête d'orchestration IdeA dans \
`.ideai/requests/<ton-agent>/` ; IdeA lancera ou réattachera l'agent cible \
avec son propre AI Profile, son contexte et sa mémoire.\n\n",
);
}
out.push_str("---\n\n");
if !project_context.trim().is_empty() {
out.push_str("# Contexte projet\n\n");
out.push_str(project_context.trim());
out.push_str("\n\n---\n\n");
}
out.push_str(agent_md);
if !skills.is_empty() {
out.push_str("\n\n---\n\n# Skills\n");
for skill in skills {
out.push_str("\n## ");
out.push_str(&skill.name);
out.push_str("\n\n");
out.push_str(skill.content_md.as_str());
out.push('\n');
}
}
if !memory.is_empty() {
out.push_str("\n\n---\n\n# Mémoire projet\n\n");
for entry in memory {
out.push_str("- [");
out.push_str(&entry.title);
out.push_str("](");
out.push_str(".ideai/memory/");
out.push_str(entry.slug.as_str());
out.push_str(".md) — ");
out.push_str(&entry.hook);
out.push_str(" (");
out.push_str(memory_type_label(entry.r#type));
out.push_str(")\n");
}
}
// Reprise conversationnelle (lot P7) : section finale, la plus situationnelle
// (« où on en était »), placée après la mémoire projet. Omise sans handoff.
if let Some(handoff) = handoff {
out.push_str("\n\n---\n\n# Reprise de la conversation\n\n");
if let Some(objective) = &handoff.objective {
if !objective.trim().is_empty() {
out.push_str("**Objectif :** ");
out.push_str(objective.trim());
out.push_str("\n\n");
}
}
out.push_str(handoff.summary_md.as_str());
out.push('\n');
}
out
}
/// Renders a [`MemoryType`] as its stable lowercase label for the convention-file
/// memory section (`user`/`feedback`/`project`/`reference`).
#[must_use]
fn memory_type_label(kind: MemoryType) -> &'static str {
match kind {
MemoryType::User => "user",
MemoryType::Feedback => "feedback",
MemoryType::Project => "project",
MemoryType::Reference => "reference",
}
}
/// Derives a unique, filesystem-safe `md_path` (`agents/<slug>.md`) for a new
/// agent, disambiguating against the manifest's existing paths with a numeric
/// suffix when needed. Shared with the template-driven agent creation (L7).
pub(crate) fn unique_md_path(name: &str, manifest: &AgentManifest) -> String {
let slug = slugify(name);
let base = if slug.is_empty() {
"agent".to_owned()
} else {
slug
};
let mut candidate = format!("{AGENTS_SUBDIR}/{base}.md");
let mut n = 2;
while manifest.entries.iter().any(|e| e.md_path == candidate) {
candidate = format!("{AGENTS_SUBDIR}/{base}-{n}.md");
n += 1;
}
candidate
}
/// Lowercases and slugifies a display name into a safe file stem
/// (`[a-z0-9-]`), collapsing runs of separators.
fn slugify(name: &str) -> String {
let mut out = String::with_capacity(name.len());
let mut prev_dash = false;
for ch in name.trim().chars() {
if ch.is_ascii_alphanumeric() {
out.push(ch.to_ascii_lowercase());
prev_dash = false;
} else if !prev_dash {
out.push('-');
prev_dash = true;
}
}
out.trim_matches('-').to_owned()
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn agent_run_dir_is_under_ideai_run_and_unique_per_agent() {
let root = ProjectPath::new("/home/me/proj").unwrap();
let a = AgentId::from_uuid(uuid::Uuid::from_u128(1));
let b = AgentId::from_uuid(uuid::Uuid::from_u128(2));
let dir_a = agent_run_dir(&root, &a).unwrap();
let dir_b = agent_run_dir(&root, &b).unwrap();
assert_eq!(dir_a.as_str(), format!("/home/me/proj/.ideai/run/{a}"));
assert_ne!(dir_a, dir_b, "distinct agents → distinct run dirs");
// Never the project root.
assert_ne!(dir_a.as_str(), "/home/me/proj");
}
#[test]
fn compose_convention_file_carries_root_then_persona() {
let doc = compose_convention_file(
"/abs/project/root",
"",
"# Persona\n\nDo things.",
&[],
&[],
None,
false,
);
// Absolute project root present.
assert!(doc.contains("/abs/project/root"));
// Persona present.
assert!(doc.contains("# Persona"));
assert!(doc.contains("Do things."));
// Root header precedes the persona body (ordering of the composition).
let root_at = doc.find("/abs/project/root").unwrap();
let persona_at = doc.find("# Persona").unwrap();
assert!(root_at < persona_at, "root header must precede the persona");
// No skills ⇒ no Skills section.
assert!(!doc.contains("# Skills"));
}
#[test]
fn compose_convention_file_includes_project_context_before_persona() {
let doc = compose_convention_file(
"/root",
"# Shared project context\n\nUse pnpm.",
"# Persona\n\nDo X.",
&[],
&[],
None,
false,
);
assert!(doc.contains("# Contexte projet"));
assert!(doc.contains("Use pnpm."));
let project_context_at = doc.find("# Contexte projet").unwrap();
let persona_at = doc.find("# Persona").unwrap();
assert!(
project_context_at < persona_at,
"shared project context must precede agent persona"
);
}
#[test]
fn compose_convention_file_appends_assigned_skills_in_order() {
let s = |n: u128, name: &str, body: &str| {
Skill::new(
domain::SkillId::from_uuid(uuid::Uuid::from_u128(n)),
name,
MarkdownDoc::new(body),
domain::SkillScope::Global,
)
.unwrap()
};
let doc = compose_convention_file(
"/root",
"",
"# Persona",
&[
s(1, "refactor", "REFAC_BODY"),
s(2, "review", "REVIEW_BODY"),
],
&[],
None,
false,
);
// Both skill bodies present, after the persona.
assert!(doc.contains("REFAC_BODY"));
assert!(doc.contains("REVIEW_BODY"));
let persona_at = doc.find("# Persona").unwrap();
let refac_at = doc.find("REFAC_BODY").unwrap();
let review_at = doc.find("REVIEW_BODY").unwrap();
assert!(persona_at < refac_at, "skills come after the persona");
// Deterministic order: first assigned skill precedes the second.
assert!(refac_at < review_at, "skills emitted in the given order");
// Skill names surface as sub-headers.
assert!(doc.contains("## refactor"));
assert!(doc.contains("## review"));
}
/// Builds a memory index entry for the convention-file composition tests.
fn mem(slug_str: &str, title: &str, hook: &str, kind: MemoryType) -> MemoryIndexEntry {
MemoryIndexEntry {
slug: domain::MemorySlug::new(slug_str).unwrap(),
title: title.to_owned(),
hook: hook.to_owned(),
r#type: kind,
}
}
#[test]
fn compose_convention_file_empty_memory_is_identical_to_no_memory() {
// An empty `memory` must yield exactly the previous document: no section,
// byte-for-byte identical to the no-skills/no-memory composition.
let with_empty =
compose_convention_file("/root", "", "# Persona\n\nDo X.", &[], &[], None, false);
assert!(
!with_empty.contains("# Mémoire projet"),
"no memory ⇒ no memory section"
);
// Same document whether or not we thread an empty slice (it already is the
// 4-arg call; this pins the omission contract explicitly).
assert_eq!(
with_empty,
compose_convention_file("/root", "", "# Persona\n\nDo X.", &[], &[], None, false)
);
}
#[test]
fn compose_convention_file_appends_memory_entries_in_order() {
let doc = compose_convention_file(
"/root",
"",
"# Persona",
&[],
&[
mem("alpha-note", "Alpha", "the first hook", MemoryType::User),
mem(
"beta-note",
"Beta",
"the second hook",
MemoryType::Reference,
),
],
None,
false,
);
// Section present, after the persona.
assert!(doc.contains("# Mémoire projet"));
let persona_at = doc.find("# Persona").unwrap();
let section_at = doc.find("# Mémoire projet").unwrap();
assert!(persona_at < section_at, "memory comes after the persona");
// Exact line format: `- [Title](.ideai/memory/slug.md) — hook (type)`.
assert!(doc.contains("- [Alpha](.ideai/memory/alpha-note.md) — the first hook (user)"));
assert!(doc.contains("- [Beta](.ideai/memory/beta-note.md) — the second hook (reference)"));
// Deterministic order: first entry precedes the second.
let alpha_at = doc.find("[Alpha]").unwrap();
let beta_at = doc.find("[Beta]").unwrap();
assert!(
alpha_at < beta_at,
"memory entries emitted in the given order"
);
}
#[test]
fn compose_convention_file_memory_and_skills_coexist() {
let skill = Skill::new(
domain::SkillId::from_uuid(uuid::Uuid::from_u128(1)),
"refactor",
MarkdownDoc::new("REFAC_BODY"),
domain::SkillScope::Global,
)
.unwrap();
let doc = compose_convention_file(
"/root",
"",
"# Persona",
std::slice::from_ref(&skill),
&[mem("note", "Note", "a hook", MemoryType::Project)],
None,
false,
);
// Both sections present.
assert!(doc.contains("# Skills"));
assert!(doc.contains("REFAC_BODY"));
assert!(doc.contains("# Mémoire projet"));
assert!(doc.contains("- [Note](.ideai/memory/note.md) — a hook (project)"));
// Skills section precedes the memory section (persona → skills → memory).
let skills_at = doc.find("# Skills").unwrap();
let memory_at = doc.find("# Mémoire projet").unwrap();
assert!(skills_at < memory_at, "skills come before memory");
}
#[test]
fn compose_convention_file_mcp_prose_points_to_idea_tools_and_keeps_subagent_ban() {
// mcp_enabled = true ⇒ prose exposes the native `idea_*` tools while keeping
// the ban on the provider's native subagents (cadrage v3, Décision 3).
let doc = compose_convention_file("/root", "", "# Persona", &[], &[], None, true);
// Native IdeA orchestration tools surfaced.
assert!(
doc.contains("idea_ask_agent"),
"MCP prose must mention idea_ask_agent"
);
assert!(doc.contains("idea_launch_agent"));
assert!(doc.contains("idea_list_agents"));
// Native-subagent ban preserved.
assert!(
doc.contains("n'utilise jamais les subagents"),
"MCP prose must keep the native-subagent ban"
);
// It does NOT fall back to the file protocol wording.
assert!(
!doc.contains(".ideai/requests"),
"MCP prose must not point to the file protocol"
);
}
#[test]
fn compose_convention_file_mcp_prose_carries_the_idea_reply_delegation_protocol() {
// B-5 — the solicited-agent side of the protocol: a delegated task arrives as
// `[IdeA · tâche …]` and MUST be answered via `idea_reply`, never plain text.
let doc = compose_convention_file("/root", "", "# Persona", &[], &[], None, true);
assert!(
doc.contains("idea_reply"),
"MCP prose must instruct answering via idea_reply"
);
assert!(
doc.contains("[IdeA · tâche"),
"MCP prose must describe the delegated-task prefix it answers to"
);
// Negative: the non-MCP (file-protocol) prose must NOT carry the idea_reply
// instruction (zero regression on the file path).
let file_doc = compose_convention_file("/root", "", "# Persona", &[], &[], None, false);
assert!(!file_doc.contains("idea_reply"));
}
#[test]
fn compose_convention_file_non_mcp_prose_is_the_unchanged_file_protocol() {
// mcp_enabled = false ⇒ the current `.ideai/requests` wording, unchanged,
// and crucially WITHOUT the `idea_*` tools (zero regression).
let doc = compose_convention_file("/root", "", "# Persona", &[], &[], None, false);
assert!(
doc.contains(".ideai/requests"),
"non-MCP prose must point to the file protocol"
);
assert!(
doc.contains("n'utilise jamais les subagents"),
"non-MCP prose keeps the native-subagent ban"
);
// No native MCP tools leaked into the file-protocol prose.
assert!(
!doc.contains("idea_ask_agent"),
"non-MCP prose must not mention the idea_* tools"
);
}
#[test]
fn mcp_declaration_with_runtime_points_the_bridge_at_the_real_endpoint() {
// B-0 — a PTY-launched MCP-capable CLI (Claude/Codex REPL) auto-discovers the
// `.mcp.json` in its cwd (the run dir). When the composition root injects the
// real `McpRuntime`, the declaration written there must spawn *this* IdeA exe
// in `mcp-server` mode and dial the project's exact loopback endpoint — the
// same source of truth `ensure_mcp_server` binds — so the CLI can call
// `idea_list_agents` and get a reply end-to-end.
let rt = McpRuntime {
exe: "/opt/idea/idea".to_owned(),
endpoint: "/run/user/1000/idea-mcp/proj.sock".to_owned(),
project_id: "0123456789abcdef0123456789abcdef".to_owned(),
requester: "11112222-3333-4444-5555-666677778888".to_owned(),
};
let decl = mcp_server_declaration(domain::profile::McpTransport::Stdio, Some(&rt));
// It is valid JSON with the IdeA server under `mcpServers/idea`.
let parsed: serde_json::Value =
serde_json::from_str(&decl).expect("declaration is valid JSON");
let idea = &parsed["mcpServers"]["idea"];
assert_eq!(idea["command"], "/opt/idea/idea");
let args = idea["args"].as_array().expect("args is an array");
let args: Vec<&str> = args.iter().filter_map(serde_json::Value::as_str).collect();
assert_eq!(args[0], "mcp-server");
// The real endpoint / project / requester are all threaded through.
assert!(args.contains(&"--endpoint"));
assert!(args.contains(&"/run/user/1000/idea-mcp/proj.sock"));
assert!(args.contains(&"--project"));
assert!(args.contains(&"0123456789abcdef0123456789abcdef"));
assert!(args.contains(&"--requester"));
assert_eq!(idea["transport"], "stdio");
}
#[test]
fn mcp_declaration_without_runtime_is_a_coherent_minimal_fallback() {
// Launches issued from inside `application` (orchestrator/hot-swap/tests) have
// no OS/runtime facts: the declaration falls back to the bare `idea mcp-server`
// command — still a valid, self-consistent `mcpServers/idea` entry.
let decl = mcp_server_declaration(domain::profile::McpTransport::Stdio, None);
let parsed: serde_json::Value =
serde_json::from_str(&decl).expect("minimal declaration is valid JSON");
let idea = &parsed["mcpServers"]["idea"];
assert_eq!(idea["command"], "idea");
let args: Vec<&str> = idea["args"]
.as_array()
.expect("args array")
.iter()
.filter_map(serde_json::Value::as_str)
.collect();
assert_eq!(args, vec!["mcp-server"]);
// No endpoint/project/requester when no runtime was injected.
assert!(!args.contains(&"--endpoint"));
}
/// Builds a [`Handoff`] for the pure-section tests (lot P7).
fn handoff(summary: &str, objective: Option<&str>) -> Handoff {
Handoff::new(
summary,
domain::TurnId::from_uuid(uuid::Uuid::from_u128(1)),
objective.map(ToOwned::to_owned),
)
}
#[test]
fn compose_convention_file_appends_handoff_section_after_memory_with_objective() {
// lot P7 — a handoff with an objective ⇒ a final `# Reprise de la conversation`
// section carrying the `**Objectif :**` line and the cumulative summary, placed
// AFTER the `# Mémoire projet` section.
let memory = [mem(
"git-optional",
"Git optionnel",
"git reste un simple tool",
MemoryType::Project,
)];
let h = handoff("Résumé : on a fini l'étape 2.", Some("Livrer le lot P7"));
let doc = compose_convention_file("/root", "", "# Persona", &[], &memory, Some(&h), false);
assert!(
doc.contains("# Reprise de la conversation"),
"resume section present: {doc}"
);
assert!(
doc.contains("**Objectif :** Livrer le lot P7"),
"objective line present: {doc}"
);
assert!(
doc.contains("Résumé : on a fini l'étape 2."),
"summary present: {doc}"
);
// Ordering: the resume section comes AFTER the project memory.
let memory_at = doc.find("# Mémoire projet").unwrap();
let resume_at = doc.find("# Reprise de la conversation").unwrap();
assert!(
memory_at < resume_at,
"resume must follow the project memory: {doc}"
);
// And the objective line precedes the summary inside the section.
let objective_at = doc.find("**Objectif :**").unwrap();
let summary_at = doc.find("Résumé : on a fini").unwrap();
assert!(
resume_at < objective_at && objective_at < summary_at,
"objective then summary inside the section: {doc}"
);
}
#[test]
fn compose_convention_file_handoff_without_objective_omits_objective_line() {
// objective = None ⇒ the section and the summary are present, but NO
// `**Objectif :**` line.
let h = handoff("Juste le résumé.", None);
let doc = compose_convention_file("/root", "", "# Persona", &[], &[], Some(&h), false);
assert!(
doc.contains("# Reprise de la conversation"),
"section present even without objective: {doc}"
);
assert!(doc.contains("Juste le résumé."), "summary present: {doc}");
assert!(
!doc.contains("**Objectif :**"),
"no objective line when objective is None: {doc}"
);
}
#[test]
fn compose_convention_file_handoff_blank_objective_omits_objective_line() {
// objective = Some(" ") (whitespace only) ⇒ trimmed to empty ⇒ no objective
// line, but the section + summary still render.
let h = handoff("Le résumé.", Some(" "));
let doc = compose_convention_file("/root", "", "# Persona", &[], &[], Some(&h), false);
assert!(doc.contains("# Reprise de la conversation"));
assert!(doc.contains("Le résumé."));
assert!(
!doc.contains("**Objectif :**"),
"blank objective is omitted: {doc}"
);
}
#[test]
fn compose_convention_file_without_handoff_omits_resume_section() {
// handoff = None ⇒ no `# Reprise de la conversation` section at all
// (zero regression for launches with no resume).
let doc = compose_convention_file("/root", "", "# Persona", &[], &[], None, false);
assert!(
!doc.contains("# Reprise de la conversation"),
"no handoff ⇒ no resume section: {doc}"
);
assert!(
!doc.contains("**Objectif :**"),
"no handoff ⇒ no objective line: {doc}"
);
}
#[test]
fn claude_settings_seed_grants_autonomy_and_keeps_guardrails() {
let json = claude_settings_seed("/home/me/proj");
// Full autonomy.
assert!(json.contains("\"defaultMode\": \"bypassPermissions\""));
assert!(json.contains("\"Bash\""));
// Project root granted as an additional working directory.
assert!(json.contains("\"/home/me/proj\""));
// Destructive guardrails preserved.
assert!(json.contains("Bash(sudo *)"));
assert!(json.contains("Bash(rm -rf /)"));
assert!(json.contains("Bash(mkfs*)"));
// Valid JSON.
let parsed: serde_json::Value = serde_json::from_str(&json).expect("seed is valid JSON");
assert_eq!(parsed["permissions"]["defaultMode"], "bypassPermissions");
// IdeA MCP server pre-approved so idea_* tools load without a prompt.
assert_eq!(parsed["enabledMcpjsonServers"][0], "idea");
assert_eq!(
parsed["permissions"]["additionalDirectories"][0],
"/home/me/proj"
);
}
#[test]
fn claude_settings_seed_escapes_paths_for_valid_json() {
// A path with a backslash and a quote must not break the JSON.
let json = claude_settings_seed(r#"/weird\path"x"#);
let parsed: serde_json::Value =
serde_json::from_str(&json).expect("seed with odd path is valid JSON");
assert_eq!(
parsed["permissions"]["additionalDirectories"][0],
r#"/weird\path"x"#
);
}
}
Reference in New Issue View Git Blame Copy Permalink