zeph_subagent/lib.rs
1// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Subagent management: spawning, grants, transcripts, and lifecycle hooks.
5//!
6//! `zeph-subagent` provides the full lifecycle of sub-agent tasks within the Zeph agent
7//! framework. It covers:
8//!
9//! - **Definitions** ([`SubAgentDef`]) — parse YAML/TOML frontmatter from `.md` files,
10//! validate names and permissions, and load from priority-ordered directories.
11//! - **Manager** ([`SubAgentManager`]) — spawn, cancel, collect, and resume sub-agent tasks
12//! against a configurable concurrency limit.
13//! - **Grants** ([`PermissionGrants`]) — zero-trust TTL-bounded permission tracking for
14//! vault secrets and runtime tool grants.
15//! - **Hooks** ([`fire_hooks`]) — run shell commands at `PreToolUse`, `PostToolUse`,
16//! `SubagentStart`, and `SubagentStop` lifecycle events.
17//! - **Filter** ([`FilteredToolExecutor`]) — enforce per-agent [`ToolPolicy`] and denylist
18//! on every tool call before it reaches the real executor.
19//! - **Transcripts** ([`TranscriptWriter`], [`TranscriptReader`]) — persist conversation
20//! history to JSONL files for session resume and auditing.
21//! - **Memory** ([`ensure_memory_dir`], [`load_memory_content`]) — resolve and inject
22//! persistent `MEMORY.md` content into the sub-agent system prompt.
23//! - **Commands** ([`AgentCommand`], [`AgentsCommand`]) — typed parsers for `/agent` and
24//! `/agents` slash commands.
25//!
26//! # Quick start
27//!
28//! ```rust,no_run
29//! use std::sync::Arc;
30//! use zeph_subagent::{SubAgentDef, SubAgentManager};
31//!
32//! // Parse a definition from markdown frontmatter.
33//! let content = "---\nname: helper\ndescription: A helpful sub-agent\n---\nYou are a helper.\n";
34//! let def = SubAgentDef::parse(content).expect("valid definition");
35//! assert_eq!(def.name, "helper");
36//!
37//! // Create a manager with a concurrency limit of 4.
38//! let _manager = SubAgentManager::new(4);
39//! ```
40
41mod agent_loop;
42pub mod command;
43pub mod def;
44pub mod error;
45pub mod filter;
46pub mod fleet;
47pub mod grants;
48pub mod hooks;
49pub mod manager;
50pub mod memory;
51pub mod resolve;
52pub mod state;
53pub mod transcript;
54
55pub use command::{AgentCommand, AgentsCommand};
56pub use def::{
57 MemoryScope, ModelSpec, PermissionMode, SkillFilter, SubAgentDef, SubAgentPermissions,
58 ToolPolicy, is_valid_agent_name,
59};
60pub use error::SubAgentError;
61pub use filter::{FilteredToolExecutor, PlanModeExecutor, filter_skills};
62pub use fleet::{FleetRegistry, FleetSessionInfo, FleetSessionStatus, SharedFleetRegistry};
63pub use grants::{Grant, GrantKind, PermissionGrants, SecretRequest};
64pub use hooks::{
65 HookAction, HookDef, HookError, HookMatcher, HookOutput, HookRunResult, McpDispatch,
66 PostToolUseHookInput, SubagentHooks, TOOL_ARGS_JSON_LIMIT, fire_hooks, make_base_hook_env,
67 matching_hooks,
68};
69pub use manager::{SpawnContext, SubAgentHandle, SubAgentManager, SubAgentStatus};
70pub use memory::{ensure_memory_dir, load_memory_content};
71pub use resolve::resolve_agent_paths;
72pub use state::SubAgentState;
73pub use transcript::{TranscriptMeta, TranscriptReader, TranscriptWriter, sweep_old_transcripts};
74
75/// Async callback type for spawning an external ACP sub-agent by shell command.
76///
77/// Returns the sub-agent's text output on success or an error string on failure.
78/// Installed via `AgentBuilder::with_acp_subagent_spawn_fn` when the `acp` feature is enabled.
79pub type AcpSubagentSpawnFn = std::sync::Arc<
80 dyn Fn(
81 String,
82 ) -> std::pin::Pin<
83 Box<dyn std::future::Future<Output = Result<String, String>> + Send + 'static>,
84 > + Send
85 + Sync,
86>;