Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
"""System prompt injection helpers for avibe agent backends."""
from __future__ import annotations
import logging
import os
import re
from dataclasses import dataclass
from pathlib import Path
from typing import Any, Iterable, Optional
from core.message_context import resolve_context_platform
from core.prompt_registry import RenderedPromptBlock, join_prompt_blocks, order_prompt_blocks, render_prompt, render_prompt_block
from modules.im import MessageContext
logger = logging.getLogger(__name__)
# System Prompt rendering invariants:
# - Preserve backend prompt caches: rendered bytes change only when authored
# content, stable configuration, or intentionally live catalogs change.
# - Compose complete, positive capability modules. Omit unavailable capabilities;
# keep recovery, compatibility, and operational detail in routed Skills.
# - Never branch Prompt content on turn-scoped authorization or incidental runtime
# health. Runtime policy belongs in the enforcing layer, not in its description.
# - Keep every generated collection deterministic, including Agent and Skill order.
# - Required built-in Skill routing is unconditional; installation guarantees it.
# - Show Page history rules live in its Skill; inspect workspace ownership only
# on demand, never while composing the conversation's stable prompt.
# - Working principles are a static, unconditional prefix before Session and
# capability details; never gate them on a backend, Skill, or Turn.
# - Author all injected prose in the registry. Production text and debug JSON
# must consume the same ordered rendered blocks; Studio never assembles prose.
# - The registry owns composition order. Keep static Skill usage guidance after
# the base capabilities and dynamic Skill rows near the end to protect caches.
# - Agent-authored instructions are the final content block, after all Avibe
# guidance and catalogs; backends must not prepend or append their own copy.
#: The main Bot's name in prompts while the user has not named it (``docs/plans/bots.md`` D5).
MAIN_BOT_DEFAULT_DISPLAY_NAME = "Vibey"
@dataclass(frozen=True)
class AgentPromptInfo:
name: str
description: str
backend: str = "unknown"
#: Set when the Agent is a Bot: the Bots table lists it, and the Agents table leaves it out.
bot_handle: str = ""
bot_display_name: str = ""
bot_position: int = 0
bot_builtin: bool = False
@dataclass(frozen=True)
class BotPromptInfo:
"""The Bot a Vibey Turn runs as, for its own sections (``docs/plans/bots.md`` "Prompt drafts").
Every field is a fact of the Bot, never of the Session or Turn, so a Bot's sections are byte-stable across its
Turns and identical in its forks, which keep its directory (D7).
"""
handle: str
display_name: str
role: str
session_id: str
workdir: str
builtin: bool = False
def _codex_generated_images_block() -> RenderedPromptBlock:
codex_home = Path(os.environ.get("CODEX_HOME") or Path.home() / ".codex").expanduser().resolve()
example_uri = (codex_home / "generated_images" / "thread-id" / "image-file.png").as_uri()
return render_prompt_block("codex-generated-images", example_uri=example_uri)
def _extract_default_session_id(context: MessageContext) -> str:
platform_specific = context.platform_specific or {}
default_session_id = platform_specific.get("agent_session_id")
if not default_session_id:
raise ValueError("agent_session_id is required before building avibe capability prompt")
return str(default_session_id)
def _extract_fork_source_session_id(context: MessageContext) -> Optional[str]:
platform_specific = context.platform_specific or {}
target = platform_specific.get("agent_session_target")
if not isinstance(target, dict):
return None
fork = target.get("native_session_fork")
if isinstance(fork, dict):
source_session_id = str(fork.get("source_session_id") or "").strip()
if source_session_id:
return source_session_id
metadata = target.get("metadata")
if isinstance(metadata, dict):
source_session_id = str(metadata.get("fork_source_session_id") or "").strip()
if source_session_id:
return source_session_id
return None
def build_forked_session_correction_prompt(context: MessageContext) -> Optional[str]:
default_session_id = _extract_default_session_id(context)
source_session_id = _extract_fork_source_session_id(context)
if source_session_id and source_session_id != default_session_id:
return render_prompt(
"forked-session-prompt",
default_session_id=default_session_id,
source_session_id=source_session_id,
)
return None
def _is_web_platform(platform: str) -> bool:
return platform.strip().lower() in {"avibe", "web"}
def _agent_bot_fields(agent: Any) -> dict[str, Any]:
"""The Bot an Agent is, from an Agent record, its list payload (``bot``), or an already coerced row."""
if isinstance(agent, AgentPromptInfo):
return {
"bot_handle": agent.bot_handle,
"bot_display_name": agent.bot_display_name,
"bot_position": agent.bot_position,
"bot_builtin": agent.bot_builtin,
}
if isinstance(agent, dict):
bot = agent.get("bot")
builtin = bool(bot.get("builtin")) if isinstance(bot, dict) else False
else:
from core.vibe_agents import agent_bot_record, is_main_bot_agent
try:
bot = agent_bot_record(agent) if getattr(agent, "archived_at", None) is None else None
builtin = bool(bot) and is_main_bot_agent(agent)
except (AttributeError, TypeError):
bot, builtin = None, False
if not isinstance(bot, dict) or not str(bot.get("handle") or "").strip():
return {}
try:
position = int(bot.get("position") or 0)
except (TypeError, ValueError):
position = 0
return {
"bot_handle": str(bot["handle"]).strip(),
"bot_display_name": str(bot.get("display_name") or "").strip(),
"bot_position": position,
"bot_builtin": builtin,
}
def _coerce_agent_prompt_info(agent: Any) -> AgentPromptInfo:
if isinstance(agent, dict):
raw_name = str(agent.get("name") or "").strip()
normalized_name = str(agent.get("normalized_name") or "").strip()
description = str(agent.get("description") or "").strip()
backend = str(agent.get("backend") or "").strip()
else:
raw_name = str(getattr(agent, "name", "") or "").strip()
normalized_name = str(getattr(agent, "normalized_name", "") or "").strip()
description = str(getattr(agent, "description", "") or "").strip()
backend = str(getattr(agent, "backend", "") or "").strip()
name = normalized_name or _normalize_agent_name_for_prompt(raw_name)
if not name:
raise ValueError("agent name is required")
return AgentPromptInfo(
name=name,
description=description or "(no description)",
backend=backend or "unknown",
**_agent_bot_fields(agent),
)
def _normalize_agent_name_for_prompt(name: str) -> str:
return re.sub(r"[^a-z0-9_-]+", "-", str(name or "").strip().lower()).strip("-_")
def _escape_markdown_table_cell(value: str) -> str:
return str(value).replace("\\", "\\\\").replace("|", "\\|").replace("\n", " ").strip()
def _coerce_enabled_agents(enabled_agents: Optional[Iterable[Any]]) -> list[AgentPromptInfo]:
rows: list[AgentPromptInfo] = []
for agent in enabled_agents or ():
try:
rows.append(_coerce_agent_prompt_info(agent))
except ValueError:
logger.debug("Skipping enabled Agent prompt row with no name: %r", agent)
return rows
def _bot_display_name(name: str, *, builtin: bool) -> str:
return name or (MAIN_BOT_DEFAULT_DISPLAY_NAME if builtin else "")
def _format_bots_rows(rows: list[AgentPromptInfo]) -> str:
"""The Bots table: the main Bot first, then by position, as the Web strip orders them."""
bots = sorted(
(row for row in rows if row.bot_handle),
key=lambda row: (0 if row.bot_builtin else 1, row.bot_position, row.bot_handle),
)
return "\n".join(
f"| {_escape_markdown_table_cell(bot.bot_handle)} | "
f"{_escape_markdown_table_cell(_bot_display_name(bot.bot_display_name, builtin=bot.bot_builtin))} | "
f"{_escape_markdown_table_cell(bot.description)} |"
for bot in bots
)
def _format_enabled_agents_rows(rows: list[AgentPromptInfo]) -> str:
"""The Agents table. An Agent that is a Bot is listed once, as the Bot (``bots.md`` D4)."""
rows = [row for row in rows if not row.bot_handle]
if not rows:
return ""
lines = []
for agent in sorted(
rows,
key=lambda item: (
item.name.casefold(),
item.name,
item.backend.casefold(),
item.backend,
item.description,
),
):
lines.append(
f"| {_escape_markdown_table_cell(agent.name)} | "
f"{_escape_markdown_table_cell(agent.backend)} | "
f"{_escape_markdown_table_cell(agent.description)} |"
)
return "\n".join(lines)
def _role_sentence(role: str) -> str:
text = " ".join(str(role or "").split())
if not text:
return ""
return f" Your role: {text}" + ("" if text[-1] in ".!?。!?" else ".")
def _bot_blocks(bot: BotPromptInfo) -> list[RenderedPromptBlock]:
blocks = [
render_prompt_block(
"bot-identity-prompt",
display_name=_bot_display_name(" ".join(bot.display_name.split()), builtin=bot.builtin) or bot.handle,
handle=bot.handle,
role_sentence=_role_sentence(bot.role),
session_id=bot.session_id,
),
render_prompt_block("bot-memory-prompt", workdir=bot.workdir, session_id=bot.session_id),
]
if bot.builtin:
blocks.append(render_prompt_block("bot-main-prompt"))
return blocks
def bot_for_turn(store: Any, *, agent_id: Optional[str], cwd: str) -> Optional[BotPromptInfo]:
"""The Bot a Turn runs as: its Agent is the Bot's, and it runs in the Bot's directory.
This is the one rule for the Bot sections, and it needs no Session id: the Bot's own Session runs there, and so
does every fork of it, since forks keep the source's directory (``bots.md`` D7). A fork therefore shares its
source's sections and its cached prefix; a fresh ``--agent`` Session of the same Agent runs elsewhere and is an
ordinary worker. Reads the catalog: call it off the event loop.
"""
if store is None or not agent_id or not cwd:
return None
from core.bots import bot_from_agent
agent = store.get_by_id(agent_id)
bot = bot_from_agent(agent) if agent is not None else None
if bot is None or os.path.realpath(cwd) != os.path.realpath(bot.directory):
return None
return BotPromptInfo(
handle=bot.handle,
display_name=bot.display_name,
role=bot.role,
session_id=bot.session_id,
workdir=str(bot.directory),
builtin=bot.builtin,
)
def get_enabled_agents_for_prompt(controller: Any) -> Optional[list[AgentPromptInfo]]:
store = getattr(controller, "vibe_agent_store", None)
if store is None:
return None
try:
agents = store.list_agents(include_disabled=False)
except Exception as exc:
logger.warning("Failed to list enabled Agents for prompt injection: %s", exc)
return None
rows: list[AgentPromptInfo] = []
for agent in agents:
try:
rows.append(_coerce_agent_prompt_info(agent))
except ValueError:
logger.debug("Skipping enabled Agent prompt row with no name: %r", agent)
return rows
def build_system_prompt_blocks(
*,
agent_instructions: str = "",
backend: str = "",
include_quick_replies: bool = True,
include_codex_generated_images: bool = False,
include_context_guidance: bool = True,
context: Optional[MessageContext] = None,
fallback_platform: Optional[str] = None,
enabled_agents: Optional[Iterable[Any]] = None,
skills_cwd: str | Path | None = None,
skills_project_base: str | Path | None = None,
skill_catalog_sink: list[dict[str, Any]] | None = None,
bot: BotPromptInfo | None = None,
) -> list[RenderedPromptBlock]:
"""The production composition, also exported by the debug command.
``bot`` is the Bot a Vibey Turn runs as (``bot_for_turn``); only then are the Bot sections rendered.
"""
skills = None
if skills_cwd is not None:
from core.managed_skills import resolve_skills
skills = resolve_skills(
skills_cwd,
project_base=skills_project_base,
)
advertisable_skills = [] if skills is None else [skill for skill in skills if not skill.disable_model_invocation]
vault_skill_available = any(
skill.name == "use-avibe-vault" for skill in advertisable_skills
)
blocks = [
render_prompt_block("base-capabilities-intro"),
render_prompt_block("agent-working-principles"),
]
if isinstance(bot, dict):
bot = BotPromptInfo(**bot)
if bot is not None:
blocks.extend(_bot_blocks(bot))
if context is not None and backend != "vibey":
blocks.append(render_prompt_block("session-start-prompt", default_session_id=_extract_default_session_id(context)))
correction = build_forked_session_correction_prompt(context)
if correction:
blocks.append(RenderedPromptBlock("forked-session-prompt", correction))
blocks.append(render_prompt_block("base-capabilities-body"))
if backend == "codex":
blocks.append(render_prompt_block("codex-skill-reuse"))
if include_codex_generated_images:
blocks.append(_codex_generated_images_block())
blocks.append(render_prompt_block("show-pages-prompt"))
if include_quick_replies:
blocks.append(render_prompt_block("quick-replies-prompt"))
if vault_skill_available:
blocks.append(render_prompt_block("vault-routing-prompt"))
if context is not None:
blocks.append(render_prompt_block("harness-routing-prompt"))
roster = _coerce_enabled_agents(enabled_agents)
agent_rows = _format_enabled_agents_rows(roster)
bots_rows = _format_bots_rows(roster)
if agent_rows or bots_rows:
blocks.append(
render_prompt_block("harness-agents-prompt", bots_rows=bots_rows, enabled_agents_rows=agent_rows)
)
if include_context_guidance:
blocks.append(render_prompt_block("project-context-prompt"))
from core.mcp_hub.prompt import build_mcp_prompt_blocks
blocks.extend(build_mcp_prompt_blocks())
if skills is not None:
from core.managed_skills import render_skill_catalog_blocks
blocks.extend(render_skill_catalog_blocks(skills))
if skill_catalog_sink is not None:
try:
from core.skill_observability import catalog_result
skill_catalog_sink.append(catalog_result(skills, entry_point="runtime_prompt"))
except Exception:
logger.info("Skill catalog observation unavailable during prompt preparation")
if context is not None and bot is None:
# A Bot's Session is titled by the Bot's display name, so it gets no title section (bots.md D5).
platform = resolve_context_platform(context, fallback_platform=fallback_platform, default="<platform>")
if _is_web_platform(platform):
blocks.append(render_prompt_block("session-title-prompt"))
if agent_instructions:
blocks.append(render_prompt_block("agent-instructions", agent_instructions=agent_instructions))
return order_prompt_blocks(blocks)
def build_system_prompt_injection(**kwargs: Any) -> str:
"""Render the production blocks without changing their byte boundaries."""
return join_prompt_blocks(build_system_prompt_blocks(**kwargs))