algocline_core/
engine_api.rs

1use async_trait::async_trait;
2
3// ─── Parameter types (transport-independent) ─────────────────────
4
5/// A single query response in a batch feed.
6#[derive(Debug)]
7pub struct QueryResponse {
8    /// Query ID (e.g. "q-0", "q-1").
9    pub query_id: String,
10    /// The host LLM's response for this query.
11    pub response: String,
12    /// Token usage reported by the host for this query.
13    pub usage: Option<crate::TokenUsage>,
14}
15
16// ─── Engine API trait ────────────────────────────────────────────
17
18/// Transport-independent API for the algocline engine.
19///
20/// Abstracts the full public surface of AppService so that callers
21/// (MCP handler, future daemon client, etc.) can operate through
22/// `Arc<dyn EngineApi>` without depending on the concrete implementation.
23///
24/// All methods are async to support both local (in-process) and remote
25/// (socket/HTTP) implementations uniformly.
26#[async_trait]
27pub trait EngineApi: Send + Sync {
28    // ─── Core execution ──────────────────────────────────────
29
30    /// Execute Lua code with optional JSON context.
31    async fn run(
32        &self,
33        code: Option<String>,
34        code_file: Option<String>,
35        ctx: Option<serde_json::Value>,
36        project_root: Option<String>,
37    ) -> Result<String, String>;
38
39    /// Apply an installed strategy package. Task is optional.
40    async fn advice(
41        &self,
42        strategy: &str,
43        task: Option<String>,
44        opts: Option<serde_json::Value>,
45        project_root: Option<String>,
46    ) -> Result<String, String>;
47
48    /// Continue a paused execution — single response (with optional query_id).
49    async fn continue_single(
50        &self,
51        session_id: &str,
52        response: String,
53        query_id: Option<&str>,
54        usage: Option<crate::TokenUsage>,
55    ) -> Result<String, String>;
56
57    /// Continue a paused execution — batch feed.
58    async fn continue_batch(
59        &self,
60        session_id: &str,
61        responses: Vec<QueryResponse>,
62    ) -> Result<String, String>;
63
64    // ─── Session status ──────────────────────────────────────
65
66    /// Query active session status.
67    async fn status(&self, session_id: Option<&str>) -> Result<String, String>;
68
69    // ─── Evaluation ──────────────────────────────────────────
70
71    /// Run an evalframe evaluation suite.
72    async fn eval(
73        &self,
74        scenario: Option<String>,
75        scenario_file: Option<String>,
76        scenario_name: Option<String>,
77        strategy: &str,
78        strategy_opts: Option<serde_json::Value>,
79    ) -> Result<String, String>;
80
81    /// List eval history, optionally filtered by strategy.
82    async fn eval_history(&self, strategy: Option<&str>, limit: usize) -> Result<String, String>;
83
84    /// View a specific eval result by ID.
85    async fn eval_detail(&self, eval_id: &str) -> Result<String, String>;
86
87    /// Compare two eval results with statistical significance testing.
88    async fn eval_compare(&self, eval_id_a: &str, eval_id_b: &str) -> Result<String, String>;
89
90    // ─── Scenarios ───────────────────────────────────────────
91
92    /// List available scenarios.
93    async fn scenario_list(&self) -> Result<String, String>;
94
95    /// Show the content of a named scenario.
96    async fn scenario_show(&self, name: &str) -> Result<String, String>;
97
98    /// Install scenarios from a Git URL or local path.
99    async fn scenario_install(&self, url: String) -> Result<String, String>;
100
101    // ─── Packages ────────────────────────────────────────────
102
103    /// Link a local directory as a project-local package (no copy).
104    async fn pkg_link(&self, path: String, project_root: Option<String>) -> Result<String, String>;
105
106    /// List installed packages with metadata.
107    ///
108    /// When `project_root` is provided, project-local packages from `alc.lock`
109    /// are included with `scope: "project"`. Global packages carry `scope: "global"`.
110    async fn pkg_list(&self, project_root: Option<String>) -> Result<String, String>;
111
112    /// Install a package from a Git URL or local path.
113    async fn pkg_install(&self, url: String, name: Option<String>) -> Result<String, String>;
114
115    /// Remove an installed package.
116    ///
117    /// - `project_root` provided or `scope == "project"`: removes from `alc.lock` only.
118    /// - `scope == "global"`: removes from `~/.algocline/packages/` regardless of project.
119    /// - Both `None`: auto-detect (project first, global fallback).
120    async fn pkg_remove(
121        &self,
122        name: &str,
123        project_root: Option<String>,
124        scope: Option<String>,
125    ) -> Result<String, String>;
126
127    // ─── Logging ─────────────────────────────────────────────
128
129    /// Append a note to a session's log file.
130    async fn add_note(
131        &self,
132        session_id: &str,
133        content: &str,
134        title: Option<&str>,
135    ) -> Result<String, String>;
136
137    /// View session logs.
138    async fn log_view(
139        &self,
140        session_id: Option<&str>,
141        limit: Option<usize>,
142        max_chars: Option<usize>,
143    ) -> Result<String, String>;
144
145    /// Aggregate stats across all logged sessions.
146    async fn stats(
147        &self,
148        strategy_filter: Option<&str>,
149        days: Option<u64>,
150    ) -> Result<String, String>;
151
152    // ─── Diagnostics ─────────────────────────────────────────
153
154    /// Show server configuration and diagnostic info.
155    async fn info(&self) -> String;
156}
algocline_core/engine_api.rs

algocline_core/
engine_api.rs
