anda: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents working in this repository.

Agent Workflow

• Work independently as the current agent. Do not spawn or delegate work to subagents.
• Before editing, run git status --short, confirm the current branch, and inspect existing diffs in the files you intend to change. Preserve the user's existing work; do not overwrite or revert unrelated files or changes.
• Use rg for search and focused reads before editing. Do not assume module boundaries from filenames alone.
• Before committing, review the final diff and stage only the files or hunks belonging to the requested task.
• At completion, briefly summarize the changes, the checks actually run and their results, and any checks not run or blocked. Never report an unrun check as passing. When committing, include the branch and commit ID in the summary.

Repository Shape

anda is a Rust workspace for composable AI agent runtimes.

• anda_core: stable traits, shared data models, context capabilities, JSON schema helpers, and RPC helpers.
• anda_engine: runtime orchestration, contexts, model adapters, tools, hooks, memory, subagents, and reusable extensions.
• anda_engine_server: HTTP server layer for exposing engines.
• anda_cli: CLI entrypoint for configured engine servers.
• anda_web3_client: Web3 integration for non-TEE environments.
• docs/architecture.md: source-level runtime architecture.
• MCP_INTEGRATION.md: MCP host/client design and boundaries.

Keep anda_core small and dependency-light. Runtime integrations belong in anda_engine or higher-level crates unless the shared contract genuinely needs to change.

Working Rules

• Inspect the exact code and docs relevant to the request before editing.
• Preserve user or agent changes already present in the working tree. Do not revert unrelated dirty files.
• Prefer small, behavior-focused changes over broad refactors.
• Keep public API changes coherent across code, docs, examples, and tests.
• Use workspace dependencies from the root Cargo.toml; do not add duplicate per-crate versions unless there is a clear reason.
• Keep generated schemas and protocol-visible names stable. Agent, tool, and provider names must satisfy the function-name rules: lowercase ASCII letters, digits, underscores, and hyphens, starting with a lowercase letter, max 64 bytes.
• Never use oneOf, anyOf or allOf in a model-facing schema: tool and agent parameters, MCP-exposed tool schemas, and structured-output schemas. Anthropic rejects them at the top level of a tool's input_schema and fails the whole request with a 400 (KIP's top-level oneOf once broke every Brain pass on Claude); strict modes reject them anywhere. Write a nullable field as a type list ("type": ["string", "null"]), alternatives of distinct types as one schema with a type list, and tagged variants as one object with an enum discriminator and the variant-only fields nullable or optional (see memory_tool_schema). Enforce cross-field rules such as "exactly one of command or operations" when parsing the arguments, and state them in the descriptions. schemars derives these keywords from Option<Struct> and enums, so check the generated JSON (extension_tool_definitions_are_strict_and_union_free). The Anthropic adapter drops top-level combinators only as a safety net for external MCP schemas; it is not a way to keep them in our own.
• When changing model/provider conversion code, preserve raw-history and tool/user message boundaries. Do not merge tool outputs into user messages or lose provider-specific content unless the existing code explicitly does so.
• ContentPart / chat_history is the persisted, provider-neutral history. Provider per-turn intermediate state (Anthropic thinking.signature, Gemini thoughtSignature) belongs in CompletionRequest::raw_history, which every adapter sends ahead of the converted chat_history and which is scoped to one in-process reasoning round. Do not add provider-specific fields to ContentPart to carry such state — an adapter dropping it on the way in is correct by design. Do fix the reverse: converting out of ContentPart must never emit something the provider rejects (e.g. a thinking block with an empty signature); omit it instead.