Struct AppService 

pub struct AppService { /* private fields */ }

Implementations

impl AppService

pub fn card_list(&self, pkg: Option<&str>) -> Result<String, String>

List Cards as JSON summaries, optionally filtered by package.

pub fn card_get(&self, card_id: &str) -> Result<String, String>

Fetch full Card body (Tier 1) by id.

pub fn card_find( &self, pkg: Option<String>, where_: Option<Value>, order_by: Option<Value>, limit: Option<usize>, offset: Option<usize>, ) -> Result<String, String>

Query Cards using the where DSL + order_by / limit / offset.

pub fn card_get_by_alias(&self, name: &str) -> Result<String, String>

Resolve alias then fetch the full Card.

pub fn card_alias_list(&self, pkg: Option<&str>) -> Result<String, String>

List aliases, optionally filtered by package.

pub fn card_alias_set( &self, name: &str, card_id: &str, pkg: Option<&str>, note: Option<&str>, ) -> Result<String, String>

Pin or rebind a mutable alias to a Card.

pub fn card_append( &self, card_id: &str, fields: Value, ) -> Result<String, String>

Additive-only annotation — new top-level keys only.

pub async fn card_install(&self, url: String) -> Result<String, String>

Install Cards from a Card Collection repo (Git URL or local path).

A Card Collection is identified by alc_cards.toml at the repo root. Each subdirectory is treated as a package name, and *.toml card files within are imported into ~/.algocline/cards/{pkg}/.

pub fn card_samples( &self, card_id: &str, offset: usize, limit: Option<usize>, where_: Option<Value>, ) -> Result<String, String>

Read per-case sidecar rows (Tier 2) with where filtering and paging.

pub fn card_lineage( &self, card_id: &str, direction: Option<&str>, depth: Option<usize>, include_stats: Option<bool>, relation_filter: Option<Vec<String>>, ) -> Result<String, String>

Walk a Card’s lineage tree via metadata.prior_card_id.

pub fn card_sink_backfill( &self, params: SinkBackfillParams, ) -> Result<String, String>

Backfill one subscriber (sink URI) with all cards from the primary store. Drift-safe: existing cards on the subscriber are skipped, never overwritten. Returns the card::SinkBackfillReport serialized as JSON for MCP transport.

pub async fn card_analyze( &self, card_id: &str, pkg: Option<String>, ) -> Result<String, String>

Load a Card + its samples sidecar and dispatch them to a Lua analyzer package.

The host owns Card-schema parsing (Tier 1 body + Tier 2 samples.jsonl) so the analyzer pkg gets a ready-to-use ctx shape. The pkg owns prompt construction + alc.llm + hint formatting.

pkg defaults to [DEFAULT_CARD_ANALYZE_PKG] when omitted — an IF promise, not a bundled hard dependency. The call delegates to AppService::advice, so all of advice’s machinery (auto-install bundled fallback, start_and_tick, response warning splicing) applies.

ctx shape passed to the pkg’s M.run(ctx):

{
  "card_id": "<id>",
  "card":    <full Card body, same shape as alc_card_get>,
  "samples": [<sidecar rows, same shape as alc_card_samples>]
}

The pkg is responsible for filtering failures, building prompts, and shaping the result.

impl AppService

pub fn hub_dist( &self, source_dir: &str, output_path: Option<&str>, out_dir: Option<&str>, preset: Option<&str>, project_root: Option<&str>, projections: Option<&[String]>, config_path: Option<&str>, lint_strict: Option<bool>, ) -> Result<String, String>

Run hub_reindex followed by hub_gendoc as a single call.

See the module-level doc comment for error semantics. source_dir is forwarded to both steps; output_path is the reindex hub_index.json destination (callers typically point this at {source_dir}/hub_index.json); the remaining arguments are forwarded to hub_gendoc unchanged.

impl AppService

pub async fn eval( &self, scenario: Option<String>, scenario_file: Option<String>, scenario_name: Option<String>, strategy: &str, strategy_opts: Option<Value>, auto_card: bool, ) -> Result<String, String>

Run an evalframe evaluation suite via alc.eval().

Resolves the scenario from one of three input modes (inline/file/name), injects the std global shim, and delegates to alc.eval() in prelude which handles evalframe loading, provider wiring, and optional Card emission.

Security: strategy is not sanitized

strategy is interpolated into a Lua string literal without escaping. This is intentional — algocline runs Lua in the caller’s own process with full ambient authority, so Lua injection does not cross a trust boundary.

pub fn eval_history( &self, strategy: Option<&str>, limit: usize, ) -> Result<String, String>

List eval history, optionally filtered by strategy.

pub fn eval_detail(&self, eval_id: &str) -> Result<String, String>

View a specific eval result by ID.

pub async fn eval_compare( &self, eval_id_a: &str, eval_id_b: &str, ) -> Result<String, String>

Compare two eval results with statistical significance testing.

Delegates to evalframe’s stats.welch_t (single source of truth for t-distribution table and test logic). Reads persisted aggregated.scores from each eval result — no re-computation of descriptive statistics.

The comparison result is persisted to ~/.algocline/evals/ so repeated lookups of the same pair are file reads only.

impl AppService

pub fn hub_gendoc( &self, source_dir: &str, out_dir: Option<&str>, projections: Option<&[String]>, config_path: Option<&str>, lint_strict: Option<bool>, ) -> Result<String, String>

See crate::EngineApi::hub_gendoc for parameter semantics.

config_path format (TOML):

[context7]
projectTitle = "my project"
description = "..."
rules = []

[devin]
project_name = "my project"

Notes:

• context7 / devin are optional individually.
• When present, each key must be a table.
• TOML arrays/tables are converted recursively to Lua tables.
• See docs/hub-gendoc-config.md for a concrete schema example.

Returns a JSON string of the form:

{ "source_dir": "...", "out_dir": "...", "stdout": "...", "stderr": "..." }

Non-zero os.exit, missing hub_index.json, Lua runtime errors, and config_path read failures are all surfaced as Err with a gendoc: prefix.

impl AppService

pub fn hub_reindex( &self, output_path: Option<&str>, source_dir: Option<&str>, ) -> Result<String, String>

Generate a hub index from a packages directory.

When source_dir is provided, scans that directory (e.g. a repo checkout) — pure metadata extraction, no manifest or card data mixed in. When omitted, scans ~/.algocline/packages/.

Writes the index to output_path (for CI / publishing). Does NOT touch the remote search cache.

pub fn hub_info(&self, pkg: &str) -> Result<String, String>

Show detailed information for a single package.

Aggregates package metadata (from index or local init.lua), all Cards, aliases, and eval stats into one response.

impl AppService

pub async fn init(&self, project_root: Option<String>) -> Result<String, String>

impl AppService

pub async fn add_note( &self, session_id: &str, content: &str, title: Option<&str>, ) -> Result<String, String>

Append a note to a session’s log file.

pub async fn log_view( &self, session_id: Option<&str>, limit: Option<usize>, max_chars: Option<usize>, ) -> Result<String, String>

View session logs.

pub fn info(&self) -> String

Return diagnostic info about the current configuration (mise doctor style).

pub fn stats( &self, strategy_filter: Option<&str>, days: Option<u64>, ) -> Result<String, String>

Aggregate stats across all logged sessions.

Scans .meta.json files (with .json fallback for legacy logs). Optional filters: strategy (exact match), days (last N days).

Legacy log compatibility

Token fields (prompt_tokens, response_tokens) were introduced in v0.12. Logs written by earlier versions lack these fields entirely. When absent, the aggregation treats them as 0 (via unwrap_or(0)) — the same pattern used for other numeric fields (elapsed_ms, total_prompt_chars, etc.). This means per-strategy total_tokens may under-report if the dataset includes pre-v0.12 sessions.

impl AppService

pub async fn migrate( &self, project_root: Option<String>, ) -> Result<String, String>

impl AppService

pub async fn pkg_doctor( &self, name: Option<String>, project_root: Option<String>, ) -> Result<String, String>

Diagnose package state without any side effects. Returns a JSON string with nine arrays (healthy, incomplete_pkg, installed_missing, missing_hub_index, missing_meta, path_missing, spec_missing, stale_cache, symlink_dangling).

name restricts the report to a single package; None inspects every known package. project_root is only consulted for the alc.toml / alc.local.toml pass and the missing_hub_index scan. Falls back to ancestor walk from cwd when None.

Error surface matches pkg_repair:

• load_manifest() / packages_dir() failures propagate via ?.
• Per-entry fs::read_dir errors inside the unattached-symlink scan are logged via tracing::warn! and skipped (helper’s behavior).
• init.lua read errors during the incomplete check are logged via tracing::warn! and skipped (best-effort, no propagation).
• fs::read_dir / try_exists errors inside run_hub_index_pass propagate via ? (collection-root scan requires reliable fs access).
• try_exists / read_dir / file_type / metadata errors inside run_stale_cache_pass propagate via ?. metadata.modified() and .elapsed() failures (cross-platform fallback) skip the file.
• When name = Some(target) and every bucket ends empty, returns Err with the same wording used by pkg_repair.

impl AppService

pub async fn pkg_install( &self, url: String, name: Option<String>, force: Option<bool>, ) -> Result<String, String>

Install a package from a Git URL or local path (string-typed, public MCP API).

Classifies url via [classify_install_url] then delegates to AppService::pkg_install_typed. Callers that already hold a classified [InstallSource] (e.g. pkg_repair) should call the typed API directly to avoid re-classifying a stale string.

impl AppService

pub async fn pkg_remove( &self, name: &str, project_root: Option<String>, version: Option<String>, scope: Option<String>, ) -> Result<String, String>

Remove a package entry scoped by scope. See module-level docs.

Parameters:

• name: package name to remove.
• project_root: optional explicit project root. Required for "project" / "all"; ignored for "global".
• version: optional version constraint (only affects alc.lock removal in project scope; the global manifest is version-agnostic).
• scope: "project" (default, back-compat), "global", or "all". Any other value errors.

impl AppService

pub async fn pkg_repair( &self, name: Option<String>, project_root: Option<String>, ) -> Result<String, String>

Heal broken packages by re-installing from installed.json source.

name — restrict to a single package; None repairs every broken pkg. project_root — used for project / variant pkg path checks. Falls back to ancestor walk from cwd.

Returns JSON with repaired, skipped, unrepairable, failed arrays (each entry has name + per-bucket fields). Repair is best-effort: the per-pkg result is reported regardless of outcome.

impl AppService

pub async fn pkg_test( &self, pkg: Option<String>, code_file: Option<String>, code: Option<String>, spec_dir: Option<String>, filter: Option<String>, search_paths: Option<Vec<String>>, _project_root: Option<String>, ) -> Result<String, String>

Run mlua-lspec tests for a package, a single file, or inline code.

Exactly one of pkg, code_file, code must be provided. Zero or more than one returns a typed Err.

Arguments

• pkg — installed package name. Spec files are discovered under <pkg_root>/<spec_dir>/*_spec.lua (default spec_dir = "spec").
• code_file — absolute path to a single .lua test file.
• code — inline Lua source code containing lspec tests.
• spec_dir — subdirectory inside the pkg root for spec files (default "spec"). Only used when pkg is provided.
• filter — substring filter on spec file stems (only for pkg).
• search_paths — additional dirs prepended to package.path inside the Lua VM.
• project_root — optional project root for variant-scope resolution (alc.local.toml). Falls back to ancestor walk from cwd.

Returns

On success: JSON string with shape {passed, failed, pending, total, duration_ms, spec_files: [{path, passed, failed, total, duration_ms, tests: [{suite, name, passed, pending, error}]}]}.

Errors

Returns Err(String) for setup failures (VM init, pkg not found, zero spec files, I/O errors, spawn_blocking panic). Per-spec Lua crashes are absorbed, not propagated.

impl AppService

pub async fn pkg_link( &self, path: String, name: Option<String>, force: Option<bool>, scope: Option<String>, project_root: Option<String>, ) -> Result<String, String>

Link a local directory as a package.

• scope = None | Some("global"): create a symlink in ~/.algocline/packages/{name}. Unix-only (symlink).
• scope = Some("variant"): record the path in alc.local.toml at the project root. Works on all platforms (no symlink).
• Any other scope value → Err.

force is only meaningful in global scope (overwrite real dir). project_root is only consulted in variant scope.

impl AppService

pub fn pkg_scaffold( &self, name: &str, target_dir: Option<&str>, category: Option<&str>, description: Option<&str>, ) -> Result<String, String>

Generate a minimal package skeleton at <target_dir>/<name>/init.lua.

Returns a JSON string { "status": "ok", "path": "...", "bytes_written": N }. Typed errors are forwarded as Err(String) to the MCP wire layer.

impl AppService

pub async fn pkg_unlink(&self, name: String) -> Result<String, String>

Remove a symlinked package from the global cache.

• If ~/.algocline/packages/{name} is a symlink: removes it.
• If it is a real directory: returns an error directing to pkg_remove.
• If it does not exist: returns an error.

impl AppService

pub async fn run( &self, code: Option<String>, code_file: Option<String>, ctx: Option<Value>, project_root: Option<String>, host_mode: Option<bool>, ) -> Result<String, String>

Execute Lua code with optional JSON context.

When host_mode: Some(true) is passed, the call is proxied via PoolClient to a long-lived worker subprocess over a Unix domain socket. When host_mode is None or Some(false) the existing in-process Executor::start_session path is used unchanged.

Concurrency

host_mode=false (default): No additional locking beyond SessionRegistry lock C. AppService itself holds no long-lived lock during this call.

host_mode=true: Acquires RwLock<PoolRegistry> (write) and advisory fs4::FileExt::lock_exclusive to update registry.json. These locks are not held across the UDS round-trip await.

Cancel safety: cancelling this .await mid-UDS-request leaves the worker subprocess running. The registry entry persists; callers can reconnect via alc_continue after MCP restart.

pub async fn advice( &self, strategy: &str, task: Option<String>, opts: Option<Value>, project_root: Option<String>, ) -> Result<String, String>

Apply a built-in strategy to a task.

If the requested package is not installed, automatically installs the bundled package collection from GitHub before executing.

project_root — optional absolute path to the project root containing alc.lock. Falls back to ALC_PROJECT_ROOT env or ancestor walk.

pub async fn continue_batch( &self, session_id: &str, responses: Vec<QueryResponse>, ) -> Result<String, String>

Continue a paused execution — batch feed.

For pool sessions (session_id found in registry.json), each response in the batch is forwarded to the worker via PoolClient::send_request. For in-MCP sessions, the existing SessionRegistry::feed_response path is used unchanged.

pub async fn continue_single( &self, session_id: &str, response: String, query_id: Option<&str>, usage: Option<TokenUsage>, ) -> Result<String, String>

Continue a paused execution — single response (with optional query_id).

Routing is automatic: if session_id is found in registry.json (pool path), the call is proxied via PoolClient over UDS. If not found (in-MCP path), the existing SessionRegistry::feed_response is used. Both paths never coexist for the same session_id.

Concurrency

Pool path: acquires RwLock<PoolRegistry> (read) to look up the session entry, then acquires tokio::sync::Mutex inside PoolClient to serialize the UDS write. Neither lock is held across the UDS await.

In-MCP path: acquires lock C in the two-phase pattern documented on SessionRegistry::feed_response.

Cancel safety: cancelling mid-await on the pool path leaves the worker subprocess running (UDS send may have been partially written; read_line is not cancel-safe — a partial line in the buffer renders the connection unusable and PoolClient must reconnect).

impl AppService

pub fn scenario_list(&self) -> Result<String, String>

List available scenarios in ~/.algocline/scenarios/.

Per-entry I/O errors are collected in "failures" rather than aborting.

pub fn scenario_show(&self, name: &str) -> Result<String, String>

Show the content of a named scenario.

pub async fn scenario_install(&self, url: String) -> Result<String, String>

Install scenarios from a Git URL or local path into ~/.algocline/scenarios/.

Expects the source to contain .lua files (at root or in a scenarios/ subdirectory).

impl AppService

pub async fn status( &self, session_id: Option<&str>, pending_filter: Option<Value>, include_history: bool, ) -> Result<String, String>

Snapshot of all active sessions (or one by ID) for external observation.

Arguments

• session_id - When Some, returns detail for one session; when None, lists all.
• pending_filter - Optional preset name or custom field-filter for pending query projection.
• include_history - When true, each snapshot includes conversation_history (cap=10). Pass false (the default) for lightweight high-frequency polling snapshots.

Returns

JSON string with either a single session object or {active_sessions, sessions} list.

Errors

Returns Err when pending_filter is an unknown preset name or an invalid shape.

impl AppService

pub async fn update( &self, project_root: Option<String>, ) -> Result<String, String>

impl AppService

pub fn new( executor: Arc<Executor>, log_config: AppConfig, search_paths: Vec<SearchPath>, ) -> Self

Trait Implementations

impl Clone for AppService

fn clone(&self) -> AppService

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl EngineApi for AppService

Delegates each EngineApi method to the corresponding AppService inherent method via fully-qualified syntax (AppService::method(self, …)).

This avoids ambiguity between the trait method and the inherent method of the same name, preventing accidental infinite recursion if the inherent method is ever removed or renamed.

fn pkg_test<'life0, 'async_trait>( &'life0 self, pkg: Option<String>, code_file: Option<String>, code: Option<String>, spec_dir: Option<String>, filter: Option<String>, search_paths: Option<Vec<String>>, project_root: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Run mlua-lspec tests for a package, a single file, or inline code.

Forwards to AppService::pkg_test. See trait doc for full contract.

fn hub_index_aggregate<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Aggregate hub index across all registered cache sources.

Delegates to AppService::aggregate_index, then serializes the result to a JSON string. Individual source failures and registry-load failures are embedded in the response JSON under a "warnings" field so the MCP caller can observe partial failures without losing the aggregate result.

fn run<'life0, 'async_trait>( &'life0 self, code: Option<String>, code_file: Option<String>, ctx: Option<Value>, project_root: Option<String>, host_mode: Option<bool>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Execute Lua code with optional JSON context.

fn advice<'life0, 'life1, 'async_trait>( &'life0 self, strategy: &'life1 str, task: Option<String>, opts: Option<Value>, project_root: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Apply an installed strategy package. Task is optional.

fn continue_single<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, session_id: &'life1 str, response: String, query_id: Option<&'life2 str>, usage: Option<TokenUsage>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Continue a paused execution — single response (with optional query_id).

fn continue_batch<'life0, 'life1, 'async_trait>( &'life0 self, session_id: &'life1 str, responses: Vec<QueryResponse>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Continue a paused execution — batch feed.

fn status<'life0, 'life1, 'async_trait>( &'life0 self, session_id: Option<&'life1 str>, pending_filter: Option<Value>, include_history: bool, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Query active session status.

fn eval<'life0, 'life1, 'async_trait>( &'life0 self, scenario: Option<String>, scenario_file: Option<String>, scenario_name: Option<String>, strategy: &'life1 str, strategy_opts: Option<Value>, auto_card: bool, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Run an evalframe evaluation suite.

fn eval_history<'life0, 'life1, 'async_trait>( &'life0 self, strategy: Option<&'life1 str>, limit: usize, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

List eval history, optionally filtered by strategy.

fn eval_detail<'life0, 'life1, 'async_trait>( &'life0 self, eval_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

View a specific eval result by ID.

fn eval_compare<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, eval_id_a: &'life1 str, eval_id_b: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Compare two eval results with statistical significance testing.

fn scenario_list<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

List available scenarios.

fn scenario_show<'life0, 'life1, 'async_trait>( &'life0 self, name: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Show the content of a named scenario.

fn scenario_install<'life0, 'async_trait>( &'life0 self, url: String, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Install scenarios from a Git URL or local path.

fn pkg_link<'life0, 'async_trait>( &'life0 self, path: String, name: Option<String>, force: Option<bool>, scope: Option<String>, project_root: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Link a local directory as a project-local package (symlink to cache).

fn pkg_unlink<'life0, 'async_trait>( &'life0 self, name: String, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Remove a symlinked package from ~/.algocline/packages/.

fn pkg_list<'life0, 'async_trait>( &'life0 self, project_root: Option<String>, limit: Option<i32>, sort: Option<String>, filter: Option<Value>, fields: Option<Vec<String>>, verbose: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

List installed packages with metadata.

fn pkg_install<'life0, 'async_trait>( &'life0 self, url: String, name: Option<String>, force: Option<bool>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Install a package from a Git URL or local path.

fn pkg_remove<'life0, 'life1, 'async_trait>( &'life0 self, name: &'life1 str, project_root: Option<String>, version: Option<String>, scope: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Remove a package entry, scoped by scope ("project" / "global" / "all", default "project").

fn pkg_repair<'life0, 'async_trait>( &'life0 self, name: Option<String>, project_root: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Heal broken package state by reinstalling entries whose installed directory is missing. Other broken kinds (dangling symlink, declared-path missing) are surfaced as unrepairable with a suggested remediation.

fn pkg_doctor<'life0, 'async_trait>( &'life0 self, name: Option<String>, project_root: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Diagnose package state without side effects.

fn add_note<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, session_id: &'life1 str, content: &'life2 str, title: Option<&'life3 str>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Append a note to a session’s log file.

fn log_view<'life0, 'life1, 'async_trait>( &'life0 self, session_id: Option<&'life1 str>, limit: Option<usize>, max_chars: Option<usize>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

View session logs.

fn stats<'life0, 'life1, 'async_trait>( &'life0 self, strategy_filter: Option<&'life1 str>, days: Option<u64>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Aggregate stats across all logged sessions.

fn init<'life0, 'async_trait>( &'life0 self, project_root: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Initialize alc.toml in the given project root.

fn update<'life0, 'async_trait>( &'life0 self, project_root: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Re-resolve all alc.toml entries and rewrite alc.lock.

fn migrate<'life0, 'async_trait>( &'life0 self, project_root: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Migrate a legacy alc.lock to alc.toml + new alc.lock format.

fn session_new<'life0, 'async_trait>( &'life0 self, project_root: Option<String>, mode: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Activate a session pin for the current MCP connection.

fn card_list<'life0, 'async_trait>( &'life0 self, pkg: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

List Card summaries, optionally filtered by pkg.

fn card_get<'life0, 'life1, 'async_trait>( &'life0 self, card_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Fetch a full Card by id.

fn card_find<'life0, 'async_trait>( &'life0 self, pkg: Option<String>, where_: Option<Value>, order_by: Option<Value>, limit: Option<usize>, offset: Option<usize>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Filter/sort Cards using the Prisma-style where DSL.

fn card_alias_list<'life0, 'async_trait>( &'life0 self, pkg: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

List aliases, optionally filtered by pkg.

fn card_get_by_alias<'life0, 'life1, 'async_trait>( &'life0 self, name: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Resolve an alias name to its bound Card and return the full Card JSON.

fn card_alias_set<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, name: &'life1 str, card_id: &'life2 str, pkg: Option<String>, note: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Bind (or rebind) an alias to a Card.

fn card_append<'life0, 'life1, 'async_trait>( &'life0 self, card_id: &'life1 str, fields: Value, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Append new top-level fields to an existing Card (additive-only).

fn card_install<'life0, 'async_trait>( &'life0 self, url: String, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Install Cards from a Card Collection repo (Git URL or local path).

fn card_samples<'life0, 'life1, 'async_trait>( &'life0 self, card_id: &'life1 str, offset: Option<usize>, limit: Option<usize>, where_: Option<Value>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Read per-case samples from a Card’s sidecar JSONL file.

fn card_lineage<'life0, 'life1, 'async_trait>( &'life0 self, card_id: &'life1 str, direction: Option<String>, depth: Option<usize>, include_stats: Option<bool>, relation_filter: Option<Vec<String>>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Walk a Card’s lineage tree via metadata.prior_card_id.

fn card_sink_backfill<'life0, 'async_trait>( &'life0 self, sink: String, dry_run: bool, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Backfill one subscriber (sink URI) with all cards from the primary store. Drift-safe: cards already present on the sink are skipped (never overwritten). Returns a SinkBackfillReport serialized as a JSON string.

fn card_analyze<'life0, 'life1, 'async_trait>( &'life0 self, card_id: &'life1 str, pkg: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Run a Card analyzer package over a single Card.

fn hub_reindex<'life0, 'async_trait>( &'life0 self, output_path: Option<String>, source_dir: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Rebuild hub index from a packages directory.

fn hub_gendoc<'life0, 'async_trait>( &'life0 self, source_dir: String, out_dir: Option<String>, projections: Option<Vec<String>>, config_path: Option<String>, lint_strict: Option<bool>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Generate human-readable documentation artifacts from a hub index.

fn hub_dist<'life0, 'async_trait>( &'life0 self, source_dir: String, output_path: Option<String>, out_dir: Option<String>, preset: Option<String>, project_root: Option<String>, projections: Option<Vec<String>>, config_path: Option<String>, lint_strict: Option<bool>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Run hub_reindex followed by hub_gendoc as a single facade.

fn hub_info<'life0, 'async_trait>( &'life0 self, pkg: String, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Show detailed information for a single package.

fn hub_search<'life0, 'async_trait>( &'life0 self, query: Option<String>, category: Option<String>, installed_only: Option<bool>, limit: Option<i32>, sort: Option<String>, filter: Option<Value>, fields: Option<Vec<String>>, verbose: Option<String>, local_indices: Option<Vec<String>>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Search packages across remote index + local install state.

fn pkg_read_init_lua<'life0, 'life1, 'async_trait>( &'life0 self, name: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Read the init.lua source of an installed package.

fn pkg_get_narrative_md<'life0, 'life1, 'async_trait>( &'life0 self, name: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<String>, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Render the narrative markdown for a package on-the-fly.

fn pkg_meta<'life0, 'life1, 'async_trait>( &'life0 self, name: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Read metadata for a single installed package.

fn pkg_scaffold<'life0, 'async_trait>( &'life0 self, name: String, target_dir: Option<String>, category: Option<String>, description: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Generate a minimal package skeleton at <target_dir>/<name>/init.lua.

fn info<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = String> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Show server configuration and diagnostic info.

fn pool_ensure<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Ensure pool workers are alive; GC stale entries. Idempotent.

fn pool_status<'life0, 'async_trait>( &'life0 self, sid: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Return pool worker status (registry.json + live state).

fn pool_stop<'life0, 'async_trait>( &'life0 self, sid: Option<String>, ) -> Pin<Box<dyn Future<Output = Result<String, String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Send SIGTERM to all workers (sid=None) or a single worker.

impl ExecutionService for AppService

fn spawn<'life0, 'async_trait>( &'life0 self, spec: SessionSpec, ) -> Pin<Box<dyn Future<Output = Result<SessionId, SpawnError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Spawn a new execution session from the given specification.

fn state<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 SessionId, ) -> Pin<Box<dyn Future<Output = Result<ExecutionState, StateError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Query the current state of a session.

fn resume<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 SessionId, payload: ResumePayload, ) -> Pin<Box<dyn Future<Output = Result<ResumeOutcome, ResumeError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Resume a paused session by providing LLM responses.

fn cancel<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 SessionId, reason: CancelReason, ) -> Pin<Box<dyn Future<Output = Result<(), CancelError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Request cooperative cancellation of a session.

fn observe( &self, id: &SessionId, ) -> Result<Box<dyn ObserverHandle>, ObserveError>

Subscribe to the progress event stream for a session.

fn await_terminal<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 SessionId, ) -> Pin<Box<dyn Future<Output = Result<TerminalOutcome, AwaitError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Await the terminal state of a session.