### Install Marrow-Core with Setup Script Source: https://github.com/zrr1999/marrow-core/blob/main/AGENTS.md This snippet demonstrates the process for performing a fresh installation of Marrow-Core. It involves cloning the repository and executing a setup script. Ensure you have git and sudo privileges. ```bash git clone https://github.com/zrr1999/marrow-core.git /opt/marrow-core cd /opt/marrow-core sudo ./setup.sh ``` -------------------------------- ### Install Marrow Service for Darwin Source: https://github.com/zrr1999/marrow-core/blob/main/README.md Installs the Marrow service for the Darwin platform. It requires a configuration file and specifies an output directory for the service files. This command is used to deploy the primary runtime service. ```bash marrow install-service --config marrow.toml --platform darwin --output-dir ./service-out ``` -------------------------------- ### Install Marrow Service for Linux Source: https://github.com/zrr1999/marrow-core/blob/main/README.md Installs the Marrow service for the Linux platform. It requires a configuration file and specifies an output directory for the service files. This command is used to deploy the primary runtime service. ```bash marrow install-service --config marrow.toml --platform linux --output-dir ./service-out ``` -------------------------------- ### Install Platform Service Files via CLI Source: https://context7.com/zrr1999/marrow-core/llms.txt Renders platform-specific service definitions for launchd (macOS) or systemd (Linux) based on the provided configuration. ```bash marrow install-service --config marrow.toml --output-dir ./services marrow install-service --config marrow.toml --platform darwin --output-dir ./services marrow install-service --config marrow.toml --platform linux --output-dir ./services ``` -------------------------------- ### Setup Marrow Core Workspace (Bash) Source: https://context7.com/zrr1999/marrow-core/llms.txt Initializes workspace directories for agents and casts canonical roles from the core into runtime agent configurations. This command ensures that agent environments are properly set up. Verbose output can be enabled to display the directories being created. ```bash # Initialize all configured agent workspaces marrow setup --config marrow.toml # With verbose output showing created directories marrow setup --config marrow.toml --verbose ``` -------------------------------- ### Define Configuration in TOML Source: https://context7.com/zrr1999/marrow-core/llms.txt Example of the marrow.toml configuration file structure, utilizing Pydantic-validated schemas for IPC, self-check, sync, and agent definitions. ```toml core_dir = "/opt/marrow-core" [ipc] enabled = true [self_check] enabled = true interval_seconds = 900 wake_agent = "curator" [sync] enabled = true interval_seconds = 3600 failure_backoff_seconds = 300 [[agents]] name = "curator" heartbeat_interval = 10800 heartbeat_timeout = 7200 workspace = "/Users/marrow" agent_command = "/Users/marrow/.opencode/bin/opencode run --agent curator" context_dirs = ["/Users/marrow/context.d"] log_retention_days = 7 log_max_count = 200 ``` -------------------------------- ### Manually Update Marrow-Core with Sync Command Source: https://github.com/zrr1999/marrow-core/blob/main/AGENTS.md This snippet shows how to manually update Marrow-Core using the command-line interface. It requires navigating to the installation directory and running the sync command with a configuration file. This is useful for applying updates or synchronizing configurations. ```bash cd /opt/marrow-core python -m marrow_core.cli sync-once --config marrow.toml ``` -------------------------------- ### Validate Marrow-Core Configuration Source: https://github.com/zrr1999/marrow-core/blob/main/README.md Validates the Marrow-Core configuration using the specified configuration file. This is a useful follow-up check after installation or updates to ensure everything is configured correctly. ```python python -m marrow_core.cli validate --config marrow.toml ``` -------------------------------- ### Check Marrow-Core Status Source: https://github.com/zrr1999/marrow-core/blob/main/README.md Retrieves and displays the current status of the Marrow-Core service. This command provides insights into the operational state of the installed service. ```python python -m marrow_core.cli status --config marrow.toml ``` -------------------------------- ### Run Marrow-Core Doctor Check Source: https://github.com/zrr1999/marrow-core/blob/main/README.md Executes the 'doctor' command for Marrow-Core, which performs diagnostic checks on the installation. This is a helpful tool for troubleshooting and ensuring the system is healthy. ```python python -m marrow_core.cli doctor --config marrow.toml ``` -------------------------------- ### Run Marrow Core Heartbeat Loop (Bash) Source: https://context7.com/zrr1999/marrow-core/llms.txt Starts the main Marrow Core scheduler in a persistent loop. This command executes configured agents at their intervals, runs sync supervisors, and initiates the IPC server. Options include enabling verbose logging, emitting structured JSON logs, and disabling the IPC server. ```bash # Start the persistent heartbeat scheduler with default config marrow run --config marrow.toml # Enable verbose debug logging marrow run --config marrow.toml --verbose # Emit structured JSON logs for log aggregation marrow run --config marrow.toml --json-logs # Disable IPC server for this run marrow run --config marrow.toml --no-ipc ``` -------------------------------- ### Query Marrow Core Status via IPC (Bash) Source: https://context7.com/zrr1999/marrow-core/llms.txt Queries the live heartbeat state of the running Marrow Core scheduler over the IPC socket. It returns structured JSON data containing the system's start time, uptime, and the status of each agent, including their intervals, last tick times, tick counts, and any errors. ```bash # Query live heartbeat status marrow status --config marrow.toml # Example output: # { # "started_at": 1704067200.0, # "uptime": 3600.5, # "agents": { # "curator": { # "name": "curator", # "interval": 10800, # "last_tick_at": 1704067200.0, # "next_tick_at": 1704078000.0, # "tick_count": 1, # "running": false, # "last_error": "" # } # } # } ``` -------------------------------- ### Wake Marrow Core Agent Early (Bash) Source: https://context7.com/zrr1999/marrow-core/llms.txt Triggers an immediate heartbeat tick for a specified agent, bypassing its normal scheduled interval. This command is useful for forcing an agent to run its task ahead of schedule, for example, in response to an external event. ```bash # Trigger an immediate tick for the 'curator' agent marrow wake curator --config marrow.toml ``` -------------------------------- ### Sync Marrow Core Updates (Bash) Source: https://context7.com/zrr1999/marrow-core/llms.txt Performs a bounded sync attempt to fetch remote changes and apply updates to the Marrow Core. It returns structured result codes indicating the outcome: 0 for no operation, 10 for a successful hot reload, 11 if a restart is required, and 1 for failure. An example shell script demonstrates how to interpret these codes. ```bash # Run one sync attempt marrow sync-once --config marrow.toml # Check the result code # 0 = noop (nothing changed) # 10 = reloaded (safe refresh applied) # 11 = restart_required (runtime code changed) # 1 = failed (check logs) # Example in a shell script marrow sync-once --config marrow.toml case $? in 0) echo "No changes" ;; 10) echo "Hot reload complete" ;; 11) echo "Restart required"; systemctl restart marrow-heart ;; *) echo "Sync failed" ;; esac ``` -------------------------------- ### Scaffold Workspace via CLI Source: https://context7.com/zrr1999/marrow-core/llms.txt Initializes a new workspace directory structure and generates a starter configuration file, with optional context script copying. ```bash marrow scaffold \ --workspace /Users/newagent \ --config-out /Users/newagent/marrow.toml \ --core-dir /opt/marrow-core marrow scaffold \ --workspace /Users/newagent \ --config-out /Users/newagent/marrow.toml \ --source-context-dir /opt/marrow-core/context.d ``` -------------------------------- ### Load and Validate Configuration in Python Source: https://context7.com/zrr1999/marrow-core/llms.txt Demonstrates how to use the Python API to load a TOML configuration file into a validated Pydantic model. ```python from pathlib import Path from marrow_core.config import load_config, RootConfig, AgentConfig config_path = Path("marrow.toml") root: RootConfig = load_config(config_path) print(f"Core directory: {root.core_dir}") for agent in root.agents: print(f"Agent: {agent.name}") ``` -------------------------------- ### Workspace Scaffolding Source: https://context7.com/zrr1999/marrow-core/llms.txt Facilitates the creation of workspace directories and generates essential configuration templates. ```APIDOC ## Workspace Scaffolding ### Description Facilitates the creation of workspace directories and generates essential configuration templates. ### Functions - `scaffold_workspace(workspace_path: Path, source_context_dir: Path) -> List[Path]` Creates the directory structure for a new workspace based on a source context directory. - `write_config_template(output_path: Path, core_dir: str, workspace: Path)` Generates and writes a starter configuration file (e.g., `marrow.toml`) to the specified output path. ``` -------------------------------- ### Scaffold New Workspace with Python Source: https://context7.com/zrr1999/marrow-core/llms.txt Facilitates the creation of workspace directories and generation of configuration templates using the `marrow_core.scaffold` module. `scaffold_workspace` creates the directory structure for a new workspace, returning a list of created paths. `write_config_template` generates a starter configuration file at a specified output path. ```python from pathlib import Path from marrow_core.scaffold import scaffold_workspace, write_config_template workspace = Path("/Users/newagent") config_out = Path("/Users/newagent/marrow.toml") # Create workspace skeleton created_paths = scaffold_workspace( workspace, source_context_dir=Path("/opt/marrow-core/context.d") ) print(f"Created {len(created_paths)} directories/files") # Generate starter config write_config_template( config_out, core_dir="/opt/marrow-core", workspace=workspace ) print(f"Config written to {config_out}") ``` -------------------------------- ### Gather Context and Build Prompts in Python Source: https://context7.com/zrr1999/marrow-core/llms.txt Uses the Python API to execute scripts within context directories and assemble the output into a prompt for agent processing. ```python import asyncio from marrow_core.prompting import gather_context, build_prompt async def main(): context_dirs = ["/Users/marrow/context.d"] context_blocks = await gather_context(context_dirs, timeout=15) rules = "Do not modify system files." base_prompt = "Execute high-value work now." prompt = build_prompt(base_prompt, rules, context_blocks) print(prompt) asyncio.run(main()) ``` -------------------------------- ### Manage Task Queue with Python Source: https://context7.com/zrr1999/marrow-core/llms.txt Provides Python functions to create and list filesystem-based tasks. It requires the `pathlib` module and specific functions from `marrow_core.task_queue`. The `create_task_file` function takes a directory, title, and body to create a new task file, returning its path. The `list_tasks` function retrieves all tasks from a directory, returning a list of dictionaries, each containing task details. ```python from pathlib import Path from marrow_core.task_queue import create_task_file, list_tasks task_dir = Path("/Users/marrow/tasks/queue") # Create a new task file task_path = create_task_file( task_dir, title="Implement user authentication", body="Add JWT-based auth to the /api/login endpoint" ) print(f"Created: {task_path}") # Output: Created: /Users/marrow/tasks/queue/20240101-120000-Implement-user-authentication.md # List all tasks in the queue tasks = list_tasks(task_dir) for task in tasks: print(f"{task['file']}: {task['title']}") # Output: 20240101-120000-Implement-user-authentication.md: Implement user authentication ``` -------------------------------- ### Service File Rendering Source: https://context7.com/zrr1999/marrow-core/llms.txt Generates platform-specific service definitions and writes them to the filesystem. ```APIDOC ## Service File Rendering ### Description Generates platform-specific service definitions and writes them to the filesystem. ### Functions - `render_service_files(platform: str, core_dir: str, config_path: Path, workspace: str) -> Dict[str, str]` Renders service definition files for a given platform (e.g., 'auto', 'darwin', 'linux'), core directory, configuration path, and workspace. - `write_service_files(files: Dict[str, str], output_dir: Path) -> List[Path]` Writes the rendered service definition files to the specified output directory. ``` -------------------------------- ### Render Service Files with Python Source: https://context7.com/zrr1999/marrow-core/llms.txt Generates platform-specific service definitions using the `marrow_core.services` module. `render_service_files` creates a dictionary of service file contents based on the specified platform, core directory, config path, and workspace. `write_service_files` then writes these rendered files to a specified output directory. ```python from pathlib import Path from marrow_core.services import render_service_files, write_service_files # Render for the current platform files = render_service_files( platform="auto", # or "darwin" / "linux" core_dir="/opt/marrow-core", config_path=Path("/opt/marrow-core/marrow.toml"), workspace="/Users/marrow" ) # Write to output directory output_dir = Path("./service-out") written = write_service_files(files, output_dir) for path in written: print(f"Written: {path}") ``` -------------------------------- ### List Queued Tasks via CLI Source: https://context7.com/zrr1999/marrow-core/llms.txt Displays all tasks currently waiting in the queue directory. ```bash marrow task list --config marrow.toml ``` -------------------------------- ### Interact with IPC API via Unix Socket using Bash Source: https://context7.com/zrr1999/marrow-core/llms.txt Demonstrates how to interact with the marrow core's IPC API exposed over a Unix domain socket using `curl`. This API provides endpoints for health checks, status retrieval, task management (listing and submission), and agent wake-up calls. Each command requires specifying the socket path using `--unix-socket`. ```bash # Health check curl --unix-socket /Users/marrow/runtime/state/marrow.sock \ http://localhost/health # Response: {"status": "ok"} # Get heartbeat status curl --unix-socket /Users/marrow/runtime/state/marrow.sock \ http://localhost/status # Response: { # "started_at": 1704067200.0, # "uptime": 3600.5, # "agents": {...} # } # List queued tasks curl --unix-socket /Users/marrow/runtime/state/marrow.sock \ http://localhost/tasks # Response: {"tasks": [{"file": "...", "title": "...", "created": ...}]} # Submit a new task curl --unix-socket /Users/marrow/runtime/state/marrow.sock \ -X POST -d '{"title":"Fix bug","body":"Description here"}' \ http://localhost/tasks # Response: {"ok": true, "file": "20240101-120000-Fix-bug.md"} # Wake an agent immediately curl --unix-socket /Users/marrow/runtime/state/marrow.sock \ -X POST -d '{"agent":"curator","reason":"manual trigger"}' \ http://localhost/wake # Response: {"ok": true, "agent": "curator"} ``` -------------------------------- ### Task Queue Management Source: https://context7.com/zrr1999/marrow-core/llms.txt Provides helper functions to create and list filesystem-based tasks within a specified directory. ```APIDOC ## Task Queue Management ### Description Provides helper functions to create and list filesystem-based tasks within a specified directory. ### Functions - `create_task_file(task_dir: Path, title: str, body: str) -> Path` Creates a new task file in the specified directory with a given title and body. - `list_tasks(task_dir: Path) -> List[Dict[str, Any]]` Lists all tasks found in the specified directory, returning a list of dictionaries, each containing task details like file name, title, and creation timestamp. ``` -------------------------------- ### Submit Tasks to Queue via CLI Source: https://context7.com/zrr1999/marrow-core/llms.txt Submits new tasks to the filesystem queue using IPC. Supports adding tasks with simple titles or detailed bodies. ```bash marrow task add "Review pending PRs" --config marrow.toml marrow task add "Fix authentication bug" \ --body "Users report intermittent 401 errors on the /api/user endpoint" \ --config marrow.toml ``` -------------------------------- ### IPC API - Unix Socket Endpoints Source: https://context7.com/zrr1999/marrow-core/llms.txt Exposes a minimal HTTP/1.1 API over a Unix domain socket for inter-process communication. ```APIDOC ## IPC API - Unix Socket Endpoints ### Description Exposes a minimal HTTP/1.1 API over a Unix domain socket for inter-process communication. ### Endpoints - **GET /health** Description: Performs a health check on the Marrow Core service. Example Request: ```bash curl --unix-socket /Users/marrow/runtime/state/marrow.sock http://localhost/health ``` Example Response: ```json {"status": "ok"} ``` - **GET /status** Description: Retrieves the heartbeat status, including start time, uptime, and agent information. Example Request: ```bash curl --unix-socket /Users/marrow/runtime/state/marrow.sock http://localhost/status ``` Example Response: ```json { "started_at": 1704067200.0, "uptime": 3600.5, "agents": {...} } ``` - **GET /tasks** Description: Lists all queued tasks. Example Request: ```bash curl --unix-socket /Users/marrow/runtime/state/marrow.sock http://localhost/tasks ``` Example Response: ```json {"tasks": [{"file": "...", "title": "...", "created": ...}]} ``` - **POST /tasks** Description: Submits a new task to the queue. Request Body: - **title** (string) - Required - The title of the task. - **body** (string) - Optional - A description for the task. Example Request: ```bash curl --unix-socket /Users/marrow/runtime/state/marrow.sock -X POST -d '{"title":"Fix bug","body":"Description here"}' http://localhost/tasks ``` Example Response: ```json {"ok": true, "file": "20240101-120000-Fix-bug.md"} ``` - **POST /wake** Description: Wakes an agent immediately. Request Body: - **agent** (string) - Required - The name of the agent to wake. - **reason** (string) - Optional - The reason for waking the agent. Example Request: ```bash curl --unix-socket /Users/marrow/runtime/state/marrow.sock -X POST -d '{"agent":"curator","reason":"manual trigger"}' http://localhost/wake ``` Example Response: ```json {"ok": true, "agent": "curator"} ``` ``` -------------------------------- ### Validate Marrow Core Configuration (Bash) Source: https://context7.com/zrr1999/marrow-core/llms.txt Checks the Marrow Core configuration file against its schema and displays a summary of all configured agents, including their intervals, timeouts, commands, workspaces, and context directories. The output indicates if the validation is successful. ```bash # Validate config and show agent summary marrow validate --config marrow.toml # Example output: # Agent: curator # interval : 10800s # timeout : 7200s # command : /Users/marrow/.opencode/bin/opencode run --agent curator # workspace: /Users/marrow # ctx_dirs : ['/Users/marrow/context.d'] # VALIDATE OK ``` -------------------------------- ### Dry Run Marrow Core Prompt Assembly (Bash) Source: https://context7.com/zrr1999/marrow-core/llms.txt Assembles prompts from rules, base instructions, and context scripts without executing agents. This command is valuable for debugging prompt construction and understanding how context is gathered. Verbose logging can be enabled to view the context gathering process. ```bash # Preview assembled prompts without execution marrow dry-run --config marrow.toml # Dry run with debug logging to see context gathering marrow dry-run --config marrow.toml --verbose ``` -------------------------------- ### Manage Agent Curator via CLI Source: https://context7.com/zrr1999/marrow-core/llms.txt Commands to wake the curator agent immediately, optionally providing a reason for the intervention. ```bash marrow wake curator --config marrow.toml --reason "manual intervention" marrow wake curator --config marrow.toml ``` -------------------------------- ### Wake Marrow-Core Curator Manually Source: https://github.com/zrr1999/marrow-core/blob/main/README.md Manually triggers the Marrow-Core curator process. This command is used to initiate specific actions or updates, with the 'reason' parameter providing context for the wake event. ```python python -m marrow_core.cli wake curator --config marrow.toml --reason manual ``` -------------------------------- ### Execute Single Marrow Core Tick (Bash) Source: https://context7.com/zrr1999/marrow-core/llms.txt Executes exactly one tick for each configured agent and then exits. This command is useful for testing the agent execution cycle or for integrating with cron-based scheduling. Verbose output can be enabled for detailed logging. ```bash # Execute one heartbeat tick per agent marrow run-once --config marrow.toml # Single tick with verbose output marrow run-once --config marrow.toml --verbose ``` -------------------------------- ### Run Sync Operation with Python Source: https://context7.com/zrr1999/marrow-core/llms.txt Handles core updates with structured result codes using the `marrow_core.sync` module. The `run_sync_once` function performs a synchronization operation, requiring core directory, workspace, state file, and lock file paths. It returns a `SyncResult` object containing the outcome, reason, and exit code. ```python from pathlib import Path from marrow_core.sync import run_sync_once, SyncResult outcome = run_sync_once( core_dir="/opt/marrow-core", workspace="/Users/marrow", state_file=Path("/Users/marrow/runtime/state/sync.json"), lock_file=Path("/Users/marrow/runtime/state/sync.lock") ) print(f"Result: {outcome.result.value}") # noop, reloaded, restart_required, failed print(f"Reason: {outcome.reason}") print(f"Exit code: {outcome.exit_code}") # 0, 10, 11, or 1 if outcome.result == SyncResult.RESTART_REQUIRED: print("Restarting service...") elif outcome.result == SyncResult.RELOADED: print("Hot reload complete") ``` -------------------------------- ### Define Role Hierarchy and Delegation Contracts in Python Source: https://context7.com/zrr1999/marrow-core/llms.txt This snippet imports the core role definitions and delegation policies for the Marrow Core framework. It establishes the hierarchy from top-level curators down to terminal experts, defining the structure for agent task delegation. ```python from marrow_core.contracts import ( TOP_LEVEL_AGENTS, # ('curator',) STEWARDS, # ('conductor', 'repo-steward') LEADERS, # ('refactor-lead', 'prototype-lead', 'review-lead', 'ops-lead') EXPERTS, # ('analyst', 'researcher', 'coder', 'tester', 'writer', 'git-ops', 'filer') ROLE_MODEL_TIERS, # Maps roles to 'high', 'medium', 'low' ROLE_PATHS, # Maps role names to file paths WORKSPACE_DIRS, # Required workspace directories ) # Delegation policy (prompt-level, not runtime-enforced): # curator -> stewards # stewards -> leaders # leaders -> experts # experts -> none (terminal) # Max delegation depth: 3 hops ``` -------------------------------- ### Sync Operation Source: https://context7.com/zrr1999/marrow-core/llms.txt Handles core updates and provides structured result codes for synchronization operations. ```APIDOC ## Sync Operation ### Description Handles core updates and provides structured result codes for synchronization operations. ### Functions - `run_sync_once(core_dir: str, workspace: str, state_file: Path, lock_file: Path) -> SyncResult` Executes a single synchronization operation, returning a result object containing the outcome, reason, and exit code. The `SyncResult` object has attributes like `result` (e.g., `noop`, `reloaded`, `restart_required`, `failed`), `reason`, and `exit_code`. ``` -------------------------------- ### Doctor Health Check for Marrow Core (Bash) Source: https://context7.com/zrr1999/marrow-core/llms.txt Performs comprehensive health checks on the Marrow Core environment. It verifies the existence of workspace directories, the executability of context scripts, and the availability of agent commands in the system's PATH. The output indicates the status of each check. ```bash # Run comprehensive health checks marrow doctor --config marrow.toml # Example output: # [curator] # ✓ workspace: /Users/marrow # ✓ context dir: /Users/marrow/context.d # ✓ queue.py # ✓ explore.py # ✓ command: /Users/marrow/.opencode/bin/opencode # DOCTOR OK ``` -------------------------------- ### Health Checks Source: https://context7.com/zrr1999/marrow-core/llms.txt Offers doctor-style validation functions to check the health of agents and collect health issues. ```APIDOC ## Health Checks ### Description Offers doctor-style validation functions to check the health of agents and collect health issues. ### Functions - `check_agent_health(agent: Any) -> List[str]` Performs health checks on a single agent and returns a list of any identified issues. - `collect_health_issues(config: Any) -> List[str]` Collects all health issues across all agents defined in the configuration, including extra commands. ``` -------------------------------- ### Run Health Checks with Python Source: https://context7.com/zrr1999/marrow-core/llms.txt Enables doctor-style validation functions for agents using the `marrow_core.health` module. It depends on `marrow_core.config.load_config` to load configuration. The `check_agent_health` function validates a single agent, returning any issues found. `collect_health_issues` gathers all health issues across all agents, including extra commands. ```python from marrow_core.config import load_config from marrow_core.health import check_agent_health, collect_health_issues root = load_config(Path("marrow.toml")) # Check a single agent for agent in root.agents: issues = check_agent_health(agent) if issues: print(f"Issues for {agent.name}:") for issue in issues: print(f" - {issue}") else: print(f"{agent.name}: OK") # Collect all issues including extra commands all_issues = collect_health_issues(root) if all_issues: print(f"Total issues: {len(all_issues)}") for issue in all_issues: print(f" - {issue}") ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.