Crate machi

Expand description

Machi — embeddable multi-agent runtime kernel (v1 clean break).

§Layers (implemented)

Crate	Role
`machi-types`	ids, messages, usage, errors
`machi-protocol`	tool id, content blocks, span catalogue
`machi-obs`	metrics sink, redact, recording / prometheus text
`machi-tools`	`DynTool`, stream, dispatch, approval
`machi-toolkit`	cwd-jailed fs/shell tools (feature)
`machi-llm`	sampler + mock / openai / ollama
`machi-agent`	definition, builder, discovery
`machi-state`	conversation handle, ledger, persistence
`machi-compaction`	compaction strategies
`machi-runtime`	turn, session, host, workflow adapter
`machi-workflow`	Rhai engine, journal, validate (no LLM)

§Vertical slice (canonical product path)

Session / handle → TurnRuntime → tools(+toolkit) → approval / stop gates → metrics → SessionHost spawn and/or journaled workflow (+ scratch/template).

Not implemented yet (do not assume): hooks crate, long-term memory crate, proc-macro derive, full OTEL SDK export, MCP.

Optional host capabilities (e.g. git_diff_since) require explicit setup.

Re-exports§

pub use machi_agent as agent;
pub use machi_llm as llm;
pub use machi_protocol as protocol;
pub use machi_runtime as runtime;
pub use machi_tools as tools;
pub use machi_types as types;
pub use machi_workflow as workflow;

Structs§

Agent: Session-bound agent: definition + resolved prompt + tools.
AgentBuilder: Builds a validated Agent.
AgentDefinition: Versionable agent definition (data only).
AgentId: Identifies an agent instance or nested run.
AgentOpts: Options for agent() / parallel() host spawns.
AgentRegistry: Shared agent definition catalogue for agent_type resolution.
AgentRunResult: Result of a nested agent run.
AlwaysDeny: Always denies (negative tests).
AutoApprove: Always allows (library tests / trusted offline hosts).
BreakerConfig: Configuration for CircuitBreaker.
BreakerSampler: Sampler wrapper that refuses traffic while the breaker is open.
BudgetState: Budget snapshot.
CalcTool: Evaluates a restricted arithmetic expression (+ - * / ( ) and numbers).
CircuitBreaker: Thread-safe windowed circuit breaker.
CompactionOutcome: Result of a compaction pass.
CompletionRequirement: Require a tool call before the turn may complete.
CompletionTokensDetails: Completion-side token details.
CompletionToolGate: Require a named tool to have been called in this conversation.
Deadline: An absolute deadline for a unit of work.
DispatchOutcome: Outcome for a single dispatched call.
DispatchRequest: One tool call to execute.
FileWorkflowRunStore: Directory of *.json records + optional shared journal root.
GateChain: Composite of ordered gates (first Continue wins).
IdentityAssembler: Identity assembler: uses only the definition’s resolved instructions.
ImageBlock: Inline image payload.
InProcessHost: In-process host: nested TurnRuntime with shared sampler, tool pool, and limits.
InProcessIsolation: Default isolation: same process and filesystem as the parent host.
IsolationEnv: Environment prepared for a single nested spawn.
Journal: In-memory journal with optional durable path.
JournalEntry: One recorded host call.
LifecycleFanout: Fan-out to a list of contributors.
MachiError: Kernel error with stable code, message, and optional source.
MaxMessages: Drop oldest non-system messages until max remains.
MemoryWorkflowRunStore: In-memory store for tests.
Message: A single conversation message.
MockSampler: Queue of scripted responses (FIFO) plus optional prompt-keyed responses.
NoopLifecycle: No-op contributor.
NoopMetrics: Discards all metrics (default for tests / offline).
OpenAiCompatConfig: Configuration for an OpenAI-compatible endpoint.
ProjectPromptAssembler: Prepend optional project preamble (e.g. AGENTS.md) to definition instructions.
PromptTokensDetails: Prompt-side token details.
RetryContext: Context for one failed attempt.
RetryPolicy: Configurable retry policy for crate::retrying::RetryingSampler.
RetryingSampler: Wraps an LlmSampler with retry / backoff / empty-response handling.
RunId: Identifies a turn or top-level run.
SampleRequest: One sampling request.
SampleResponse: Sampling result.
Session: Thin multi-turn orchestrator (one agent, persistent conversation state).
SessionId: Identifies a multi-turn session.
SpawnAgentTool: Tool that spawns a nested agent through a shared SessionHost.
SpawnOpts: Options for spawning a nested agent.
StaticToolSource: Fixed list of tools (primary host-registered set).
StationarityTracker: Tracks stationarity across tool-call steps within a turn.
TokenThreshold: Drop oldest non-system messages when token_estimate exceeds max_tokens.
ToolCall: A model-emitted tool invocation.
ToolCallContext: Context passed into every tool invocation.
ToolCallId: Identifies a model tool call within a turn.
ToolDefinition: JSON-schema facing tool definition for model APIs.
ToolDispatch: Scheduler for tool batches.
ToolId: Canonical tool identifier (name-based for v1).
ToolMetadata: Metadata used by dispatch and capability filters.
ToolRegistry: Thread-safe tool registry.
ToolResult: Successful tool output returned to the model.
TurnOptions: Options for a single turn.
TurnOutcome: Successful or failed turn result.
TurnRuntime: Stateless turn engine.
Usage: Aggregated token usage for a sample or turn.
ValidationReport: Successful dry-run report.
VecConversationState: In-memory conversation state.
WorkflowAgentResult: Result returned from a host agent spawn.
WorkflowMeta: Workflow catalog metadata.
WorkflowRunId: Identifies a workflow orchestration run.
WorkflowRunParams: Parameters for run_workflow.
WorkflowRunRecord: Durable metadata for one workflow run.
WorkflowSideEffects: Shared mutable store for a single workflow run.

Enums§

Admission: Admission decision.
AgentSource: Where a definition was loaded from (for discovery precedence).
ApprovalDecision: Decision for a pending tool call.
ApprovalPolicy: When to consult the approval gate.
BreakerOutcome: Outcome recorded after a probe or live call.
BreakerState: Breaker state machine.
CapabilityFlag: Fine-grained capability flags for filtering.
CapabilityMode: How nested/session capability mode filters tools.
ConcurrencyMode: How a tool interacts with concurrent execution.
ContentBlock: Rich content unit for tool progress, tool results, and multimodal messages.
ContentPart: One content part of a multimodal message.
Destructiveness: Destructiveness class for policy and approvals.
ErrorCode: Machine-stable error code for control-plane handling.
GateDecision: Result of evaluating stop gates after a final assistant message.
HostError: Host-side failures.
HttpRetryClass: HTTP classification outcome.
ImageMime: Image MIME types commonly used in multimodal prompts.
Instructions: Static or deferred instructions.
InterruptBehavior: Cancel behavior while a tool is running.
JournalError: Journal failures.
PauseKind: Why a workflow paused.
PreflightOverflow: Preflight decision before sampling.
RetryClass: Whether an automatic retry may be appropriate.
RetryDecision: Decision from the classifier.
Role: Participant role in a conversation.
SampleEvent: One event in a streaming sample.
StationarityAction: Action after observing a tool-call batch.
StoreError: Store failures.
ToolChoice: Whether the model must/may/must-not call tools.
ToolPolicy: Tool allow/deny policy on a definition (applied at agent resolution / build).
ToolProgress: Progress payload shapes.
ToolStreamItem: One item in a tool stream.
TurnAbortReason: Why a turn aborted without a normal completion.
TurnInput: User-facing turn input.
ValidationError: Validation failures.
WorkflowHostRequest: Requests the pure engine sends to the host.
WorkflowOutcome: Terminal or pausable workflow outcome.
WorkflowRunStatus: Coarse status for listing / resume UX.

Constants§

DEFAULT_AGENT_BUDGET: Default cumulative agent-call budget.
DEFAULT_IDLE_TIMEOUT: Default per-chunk idle timeout for streams (W2.2).
DEFAULT_MAX_ATTEMPTS: Default max attempts (including the first try). Attempt index reaching this is fatal.
DEFAULT_MAX_CONCURRENT_CHILDREN: Default max concurrent in-flight nested agents.
DEFAULT_MAX_SPAWN_DEPTH: Default max nesting depth for nested agents (0..DEFAULT_MAX_SPAWN_DEPTH).
EXPLORE: Read-only exploration agent.
EXTRA_SPAWN_DEPTH: Extra key: nesting depth of the agent that owns this tool call (0 = first host-spawned level). Used by spawn_agent to fail-closed on depth.
GENERAL_PURPOSE: Builtin agent type names.
HARD_STOP_THRESHOLD: Consecutive identical tool rounds before a hard stop.
IMAGE_TOKEN_COST: Fixed token cost for one image part (provider-agnostic estimate).
MAX_AGENT_BUDGET: Hard ceiling for agent budget.
MAX_DELTA_BYTES: Default max bytes per partial delta frame (16 KiB).
MAX_FRAME_BYTES: Default max total frame/stream bytes (16 MiB).
MAX_JOURNAL_BYTES: Maximum journal file size in bytes.
MAX_JOURNAL_ENTRIES: Maximum journal entries (same ceiling as host-call budget).
MAX_RETRY_AFTER: Cap when honoring full Retry-After on 429.
MAX_RETRY_BACKOFF: Cap for exponential backoff (and non-429 Retry-After clamp).
MESSAGE_FRAME_TOKENS: Framing overhead tokens per message (role + separators).
NUDGE_THRESHOLD: Consecutive identical tool rounds before a soft nudge reminder.
ORCHESTRATOR_DELEGATION_PROMPT: Orchestrator delegation guidance (host / parent system prompt fragment).
PLAN: Plan-mode agent (no execute/spawn tools).
PROJECT_AGENTS_DIR: Default relative directory under a project root.
PROJECT_AGENTS_MD: Default project instruction file relative to a workspace root.
RATE_LIMIT_RETRY_THRESHOLD: After this many 429 retries, escalate instead of waiting again.
SPAN_COMPACT: Compaction pass.
SPAN_SAMPLE: One LLM sample call.
SPAN_SESSION: Session lifetime span.
SPAN_SPAWN: Nested agent spawn.
SPAN_TOOL: One tool execution.
SPAN_TOOL_BATCH: Dispatched tool batch.
SPAN_TURN: Single turn span.
SPAN_WORKFLOW: Workflow run.
SPAN_WORKFLOW_HOST: One workflow host request.
USER_AGENTS_DIR: Relative directory under the user home.

Traits§

ApprovalGate: Host-supplied gate consulted before running tools that need confirmation.
CompactionStrategy: Pure compaction strategy.
ConversationState: Mutable conversation backing a turn or session.
DynTool: Object-safe tool.
IsolationBackend: Prepares (and later tears down) an execution environment for a child agent.
LlmSampler: Abstraction over model providers.
MetricsSink: Host-provided metrics backend.
PromptAssembler: Assembles the final system prompt for an agent definition.
SessionHost: Host capable of spawning nested agents.
StopGate: Extensible stop-gate. Gates run in order; first non-GateDecision::Complete wins.
ToolSource: Provides tools that can be merged into a ToolRegistry.
TurnLifecycleContributor: Lifecycle hooks for a single turn. Default methods are no-ops.
WorkflowRunStore: Host port for listing and resuming workflow runs.

Functions§

agents_md_path: Resolve AGENTS.md path under a project root (does not read).
backoff_for_attempt: Exponential backoff 2^attempt seconds from 2s, capped, with optional ±20% jitter.
build_chat_completions_body: Build the JSON body for Chat Completions from a kernel SampleRequest.
builtin_definitions: Built-in catalogue (always enabled).
builtin_names: Builtin name set (for user-level shadowing skip).
by_name_in_dir: Find by name in a directory (file stem or frontmatter name).
by_name_resolved: Resolve name via multi-level discovery (cwd defaults to current dir).
check_context_overflow: Check whether estimated exceeds window * threshold_ratio (clamped).
classify_http_status: Classify an HTTP status for the edge-client policy (W2.1).
decide_retry: Decide whether to retry after a MachiError.
default_probe_args: Default args used when the author does not supply probe input.
discover_in_dir: Discover *.md definitions under root (non-recursive).
discover_project: Discover under {cwd}/.machi/agents when the directory exists.
discover_user: Discover user-level agents when the directory exists.
drain_terminal: Drain a stream to the terminal result, discarding progress.
drain_with_progress: Drain a stream, collecting progress items and the terminal result.
error_code_for_http: Map HTTP class + status into a MachiError code.
estimate_conversation_tokens: Estimate tokens for a conversation (re-export of shared estimator).
estimate_image_tokens: Approximate tokens for one image attachment.
estimate_text_tokens: Approximate tokens for a UTF-8 string: ceil(bytes / 4).
evaluate_stop_gates: Evaluate configured gates for the agent against conversation history.
extract_meta: Extract meta map by evaluating the script with dummy host functions noop.
fingerprint_batch: Stable fingerprint for a batch of tool calls (order-sensitive).
is_empty_response: True when a completed response is empty (retryable EmptyResponse).
isolation_error: Map isolation failures to a typed host error.
load_file: Load a single file.
merge_arc_sources: Arc-wrapped dynamic source list helper.
merge_tool_sources: Merge multiple sources into one registry.
nudge_message: User message carrying a stationarity nudge (for injection into the buffer).
parse_chat_completions_response: Parse a Chat Completions JSON response into a kernel SampleResponse.
parse_definition_markdown: Parse a definition file: YAML frontmatter between --- fences, body = instructions.
partial_progress_frames: Split input into UTF-8-safe partial progress frames.
project_agent_dirs: Walk cwd → filesystem root collecting existing .machi/agents dirs (nearest first).
request_hash: Hash a host request for divergence detection (16 digest bytes → 32 hex chars).
resolve_agents: Full multi-level resolve with shadowing (W5.1).
response_to_stream: Convert a complete response into a short stream.
run_workflow: Run a workflow script to a terminal outcome.
run_workflow_configured: Full configuration: metrics + side-effect store (scratch / templates).
run_workflow_on_host: Run a workflow script whose agent / parallel calls resolve through host.
run_workflow_on_host_with_metrics: Like run_workflow_on_host with an explicit metrics sink.
span_catalogue_snapshot: Exact newline-joined span catalogue for CI golden comparison.
terminal_only: Single-item terminal stream from a completed result.
user_agents_dir: User home agents directory ($HOME/.machi/agents), when resolvable.
validate_script: Validate a script with the default agent budget.
validate_script_with_agent_budget: Validate with an explicit agent-call budget for the probe host.
with_progress: Progress items then a terminal future.

Type Aliases§

Result: Result alias using MachiError.
SampleStream: Opaque pinned sample event stream.
SharedMetrics: Shared metrics handle.
SharedTool: Shared tool handle.
ToolError: Tool error alias mapped into MachiError.
ToolStream: Opaque pinned stream of tool items.

Crate machi

Crate machi Copy item path

§Layers (implemented)

§Vertical slice (canonical product path)

Re-exports§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate machi