Skip to content

Agent Zero AI framework

feat(plugins): Add _promptinclude plugin for persistent system prompt files

linuztx785cf33921f3
diff --git a/plugins/_promptinclude/default_config.yaml b/plugins/_promptinclude/default_config.yaml
new file mode 100644
index 000000000..8d3da9f14
--- /dev/null
+++ b/plugins/_promptinclude/default_config.yaml
@@ -0,0 +1,18 @@
+name_pattern: "*.promptinclude.md"
+max_depth: 10
+max_file_tokens: 2000
+max_file_count: 50
+max_total_tokens: 8000
+gitignore: |
+ venv/**
+ **/__pycache__/**
+ **/node_modules/**
+ **/.npm/**
+ **/.git/**
+ **/.conda/**
+ **/.cache/**
+ **/dist/**
+ **/build/**
+ **/.tox/**
+ **/.eggs/**
+ **/*.egg-info/**
diff --git a/plugins/_promptinclude/extensions/python/system_prompt/_16_promptinclude.py b/plugins/_promptinclude/extensions/python/system_prompt/_16_promptinclude.py
new file mode 100644
index 000000000..b9d197326
--- /dev/null
+++ b/plugins/_promptinclude/extensions/python/system_prompt/_16_promptinclude.py
@@ -0,0 +1,89 @@
+from helpers.extension import Extension
+from helpers import plugins, files, runtime
+from helpers import projects
+from helpers.settings import get_settings
+from agent import Agent, LoopData
+
+from plugins._promptinclude.helpers.scanner import scan_promptinclude_files, ScanResult
+
+
+class PromptInclude(Extension):
+
+ async def execute(
+ self,
+ system_prompt: list[str] = [],
+ loop_data: LoopData = LoopData(),
+ **kwargs,
+ ):
+ if not self.agent:
+ return
+
+ config = plugins.get_plugin_config("_promptinclude", agent=self.agent) or {}
+ scan_path = _resolve_workdir(self.agent)
+
+ if not scan_path:
+ return
+
+ name_pattern = config.get("name_pattern", "*.promptinclude.md")
+ result = await runtime.call_development_function(
+ scan_promptinclude_files,
+ scan_path,
+ name_pattern=name_pattern,
+ max_depth=config.get("max_depth", 10),
+ max_file_tokens=config.get("max_file_tokens", 2000),
+ max_file_count=config.get("max_file_count", 50),
+ max_total_tokens=config.get("max_total_tokens", 8000),
+ gitignore=config.get("gitignore", ""),
+ )
+
+ if not result["files"] and result["skipped_count"] == 0:
+ prompt = self.agent.read_prompt(
+ "agent.system.promptinclude.md",
+ name_pattern=name_pattern,
+ includes="",
+ )
+ system_prompt.append(prompt)
+ return
+
+ includes = _format_includes(result)
+ prompt = self.agent.read_prompt(
+ "agent.system.promptinclude.md",
+ name_pattern=name_pattern,
+ includes=includes,
+ )
+ system_prompt.append(prompt)
+
+
+def _resolve_workdir(agent: Agent) -> str:
+ project_name = projects.get_context_project_name(agent.context)
+ if project_name:
+ folder = projects.get_project_folder(project_name)
+ if runtime.is_development():
+ folder = files.normalize_a0_path(folder)
+ return folder
+ return get_settings()["workdir_path"]
+
+
+def _format_includes(result: ScanResult) -> str:
+ lines: list[str] = []
+
+ for entry in result["files"]:
+ path = entry["path"]
+ status = entry["status"]
+ content = entry["content"]
+
+ if status == "skipped":
+ lines.append(f"{path} !!! skipped to fit")
+ continue
+
+ suffix = " !!! cropped to fit" if status == "cropped" else ""
+ lines.append(f"{path}{suffix}")
+ lines.append("```")
+ lines.append(content)
+ lines.append("```")
+ lines.append("")
+
+ if result["skipped_count"] > 0:
+ lines.append(f"!!! {result['skipped_count']} more files skipped to fit")
+
+ return "\n".join(lines)
diff --git a/plugins/_promptinclude/helpers/__init__.py b/plugins/_promptinclude/helpers/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/plugins/_promptinclude/helpers/scanner.py b/plugins/_promptinclude/helpers/scanner.py
new file mode 100644
index 000000000..9adb83a2d
--- /dev/null
+++ b/plugins/_promptinclude/helpers/scanner.py
@@ -0,0 +1,177 @@
+"""Scan workdir for promptinclude files. No agent/tool dependencies."""
+
+import fnmatch
+import os
+from typing import Literal, TypedDict
+
+from pathspec import PathSpec
+
+from helpers import tokens
+
+
+# ------------------------------------------------------------------
+# Types
+# ------------------------------------------------------------------
+
+class FileEntry(TypedDict):
+ path: str
+ content: str
+ token_count: int
+ status: Literal["ok", "cropped", "skipped"]
+
+
+class ScanResult(TypedDict):
+ files: list[FileEntry]
+ skipped_count: int
+
+
+# ------------------------------------------------------------------
+# Public API
+# ------------------------------------------------------------------
+
+def scan_promptinclude_files(
+ root: str,
+ *,
+ name_pattern: str = "*.promptinclude.md",
+ max_depth: int = 10,
+ max_file_tokens: int = 2000,
+ max_file_count: int = 50,
+ max_total_tokens: int = 8000,
+ gitignore: str = "",
+) -> ScanResult:
+ ignore_spec = _build_ignore_spec(gitignore)
+ matched = _find_matching_files(root, name_pattern, max_depth, ignore_spec)
+ matched.sort()
+
+ result_files: list[FileEntry] = []
+ total_tokens_used = 0
+ skipped_count = 0
+ budget_exhausted = False
+
+ for path in matched:
+ if budget_exhausted or len(result_files) >= max_file_count:
+ skipped_count += 1
+ continue
+
+ try:
+ with open(path, "r", encoding="utf-8", errors="replace") as f:
+ raw = f.read()
+ except (OSError, IOError):
+ skipped_count += 1
+ continue
+
+ if not raw.strip():
+ continue
+
+ file_tokens = tokens.count_tokens(raw)
+
+ # check if adding path line alone exceeds budget
+ path_tokens = tokens.count_tokens(path) + 5 # overhead for formatting
+ if total_tokens_used + path_tokens > max_total_tokens:
+ skipped_count += 1
+ budget_exhausted = True
+ continue
+
+ # per-file token cap
+ capped = min(file_tokens, max_file_tokens)
+
+ if total_tokens_used + path_tokens + capped > max_total_tokens:
+ # try to fit partial
+ remaining = max_total_tokens - total_tokens_used - path_tokens
+ if remaining > 50:
+ trimmed = tokens.trim_to_tokens(raw, remaining, direction="start")
+ trimmed_count = tokens.count_tokens(trimmed)
+ total_tokens_used += path_tokens + trimmed_count
+ result_files.append(FileEntry(
+ path=path, content=trimmed,
+ token_count=trimmed_count, status="cropped",
+ ))
+ else:
+ result_files.append(FileEntry(
+ path=path, content="",
+ token_count=0, status="skipped",
+ ))
+ budget_exhausted = True
+ continue
+
+ if capped < file_tokens:
+ trimmed = tokens.trim_to_tokens(raw, max_file_tokens, direction="start")
+ trimmed_count = tokens.count_tokens(trimmed)
+ total_tokens_used += path_tokens + trimmed_count
+ result_files.append(FileEntry(
+ path=path, content=trimmed,
+ token_count=trimmed_count, status="cropped",
+ ))
+ else:
+ total_tokens_used += path_tokens + file_tokens
+ result_files.append(FileEntry(
+ path=path, content=raw,
+ token_count=file_tokens, status="ok",
+ ))
+
+ # remaining unprocessed files from matched list
+ remaining_unprocessed = len(matched) - len(result_files) - skipped_count
+ if remaining_unprocessed > 0:
+ skipped_count += remaining_unprocessed
+
+ return ScanResult(files=result_files, skipped_count=skipped_count)
+
+
+# ------------------------------------------------------------------
+# Internal helpers
+# ------------------------------------------------------------------
+
+def _build_ignore_spec(gitignore: str) -> PathSpec | None:
+ if not gitignore or not gitignore.strip():
+ return None
+ lines = [
+ line.strip()
+ for line in gitignore.splitlines()
+ if line.strip() and not line.strip().startswith("#")
+ ]
+ if not lines:
+ return None
+ return PathSpec.from_lines("gitwildmatch", lines)
+
+
+def _find_matching_files(
+ root: str,
+ name_pattern: str,
+ max_depth: int,
+ ignore_spec: PathSpec | None,
+) -> list[str]:
+ root = os.path.abspath(root)
+ if not os.path.isdir(root):
+ return []
+
+ results: list[str] = []
+
+ for dirpath, dirnames, filenames in os.walk(root, topdown=True):
+ depth = dirpath[len(root):].count(os.sep)
+ if depth >= max_depth:
+ dirnames.clear()
+ continue
+
+ # filter ignored dirs in-place
+ if ignore_spec:
+ filtered_dirs = []
+ for d in dirnames:
+ rel = os.path.relpath(os.path.join(dirpath, d), root)
+ rel_posix = rel.replace(os.sep, "/")
+ if ignore_spec.match_file(rel_posix) or ignore_spec.match_file(f"{rel_posix}/"):
+ continue
+ filtered_dirs.append(d)
+ dirnames[:] = filtered_dirs
+
+ for fname in filenames:
+ if not fnmatch.fnmatch(fname, name_pattern):
+ continue
+ full = os.path.join(dirpath, fname)
+ if ignore_spec:
+ rel = os.path.relpath(full, root)
+ rel_posix = rel.replace(os.sep, "/")
+ if ignore_spec.match_file(rel_posix):
+ continue
+ results.append(full)
+
+ return results
diff --git a/plugins/_promptinclude/plugin.yaml b/plugins/_promptinclude/plugin.yaml
new file mode 100644
index 000000000..67bfbad22
--- /dev/null
+++ b/plugins/_promptinclude/plugin.yaml
@@ -0,0 +1,8 @@
+name: _promptinclude
+title: Prompt Include
+description: Include *.promptinclude.md files from workdir in agent system prompt.
+version: 1.0.0
+settings_sections:
+ - agent
+per_project_config: true
+per_agent_config: true
diff --git a/plugins/_promptinclude/prompts/agent.system.promptinclude.md b/plugins/_promptinclude/prompts/agent.system.promptinclude.md
new file mode 100644
index 000000000..1915f05f0
--- /dev/null
+++ b/plugins/_promptinclude/prompts/agent.system.promptinclude.md
@@ -0,0 +1,11 @@
+## system prompt includes
+create files matching "{{name_pattern}}" pattern in workdir, always present in system prompt
+use for: persistent instructions, behaviour rules, project context, reminders, style guides
+files searched recursively in workdir, sorted alphabetically by full path
+create/update/delete these files when user wants to change agent behaviour, remember instructions, or set persistent rules
+{{if includes}}
+
+### includes
+
+{{includes}}
+{{endif}}
diff --git a/plugins/_promptinclude/webui/config.html b/plugins/_promptinclude/webui/config.html
new file mode 100644
index 000000000..4376f6afe
--- /dev/null
+++ b/plugins/_promptinclude/webui/config.html
@@ -0,0 +1,97 @@
+<html>
+<head>
+ <title>Prompt Include</title>
+</head>
+
+<body>
+ <div x-data>
+ <template x-if="config">
+ <div>
+ <div class="section-title">Prompt Include</div>
+ <div class="section-description">
+ Include matching files from workdir in agent system prompt.
+ </div>
+
+ <div class="field">
+ <div class="field-label">
+ <div class="field-title">Name pattern</div>
+ <div class="field-description">
+ Glob pattern for files to include (e.g. *.promptinclude.md).
+ </div>
+ </div>
+ <div class="field-control">
+ <input type="text"
+ x-model="config.name_pattern" />
+ </div>
+ </div>
+
+ <div class="field">
+ <div class="field-label">
+ <div class="field-title">Max depth</div>
+ <div class="field-description">
+ Maximum directory depth to search.
+ </div>
+ </div>
+ <div class="field-control">
+ <input type="number" min="1" max="50"
+ x-model.number="config.max_depth" />
+ </div>
+ </div>
+
+ <div class="field">
+ <div class="field-label">
+ <div class="field-title">Max file tokens</div>
+ <div class="field-description">
+ Token limit per individual file. Longer files are cropped.
+ </div>
+ </div>
+ <div class="field-control">
+ <input type="number" min="100" max="20000"
+ x-model.number="config.max_file_tokens" />
+ </div>
+ </div>
+
+ <div class="field">
+ <div class="field-label">
+ <div class="field-title">Max file count</div>
+ <div class="field-description">
+ Maximum number of files to include.
+ </div>
+ </div>
+ <div class="field-control">
+ <input type="number" min="1" max="200"
+ x-model.number="config.max_file_count" />
+ </div>
+ </div>
+
+ <div class="field">
+ <div class="field-label">
+ <div class="field-title">Max total tokens</div>
+ <div class="field-description">
+ Total token budget for all included files combined.
+ </div>
+ </div>
+ <div class="field-control">
+ <input type="number" min="500" max="50000"
+ x-model.number="config.max_total_tokens" />
+ </div>
+ </div>
+
+ <div class="field">
+ <div class="field-label">
+ <div class="field-title">Gitignore patterns</div>
+ <div class="field-description">
+ Gitignore-style patterns to skip directories/files during search.
+ </div>
+ </div>
+ <div class="field-control">
+ <textarea rows="8"
+ x-model="config.gitignore"></textarea>
+ </div>
+ </div>
+ </div>
+ </template>
+ </div>
+</body>
+
+</html>