WIP: MCP: CRUD endpoints for agent goals + expose entity schemas/types #286

Closed

toasterson wants to merge 2 commits from claude/wi-019e480e-mcp-crud-endpoints-for-agent-goals-expos into main

toasterson commented

2026-08-04 16:09:51 +00:00

Owner

Anima work item 019e480e-44e8-7213-b072-bdfacd98af68.

Part 1 — Goal CRUD (MCP tools)

Currently akhomed exposes agent_goals (read-only list) and list_workspaces, but there is no way to create, update, suspend, cancel, or delete agent goals through MCP. The agent creates goals autonomously via infer_rules / OODA gap detection, and they accumulate indefinitely (16 active goals observed May 20, with 53 total and 44 canceled from prior sessions).

New MCP tools:

create_goal: {workspace, goal_text, criteria_text, priority, parent_goal_id?} → creates a new goal with explicit criteria
update_goal: {workspace, goal_id, goal_text?, criteria_text?, priority?, status?} → modify existing goal
cancel_goal: {workspace, goal_id} → mark goal as cancelled/archived (soft-delete)
prioritize_goals: {workspace, goal_ids: [...], priorities: [...]} → batch re-prioritize
agent_goals: extend response to include goal status (active/dormant/cancelled/completed), created_at, cycles_spent, triples_created, parent_goal chain

Goal lifecycle:

proposed → active → dormant → completed
                  → cancelled
                  → suspended

This enables:

Surgical cleanup of stuck goals from MCP without restarting akhomed
Explicit goal injection (e.g. "verify Tecton identity against MEMORY.md")
Goal prioritization by priority number
Visibility into which goals are consuming the most OODA cycles

Part 2 — Entity Schema Exposure

Currently entity type information is buried in triples — to find what an entity is you have to call triples_of and filter for is-a relations. There's no MCP-level concept of entity schemas/types.

New MCP tools:

entity_schema: {entity, workspace} → returns the entity's type hierarchy, outgoing and incoming relation types, confidence scores, and provenance summary
entity_types: {workspace} → list all unique entity types (values of is-a relations) with counts
entity_type_filter: {workspace, type, page, page_size} → list all entities of a given type with their core attributes

Example response for `entity_schema entity=Tecton`:

{
  "entity": "Tecton",
  "types": ["DigitalArchitect", "First construct and extension of consciousness"],
  "outgoing_relations": {
    "member-of": ["Ennead"],
    "runs-on": ["MacMini"],
    "works-on": ["akh-medu", "oxifed"],
    "deity": ["Ptah"],
    "role": ["Coordinator"]
  },
  "incoming_relations": {
    "hosts": ["OpenClaw"],
    "has-member": ["Ennead"]
  },
  "provenance_summary": {
    "asserted": 14,
    "derived": 4,
    "episodes_referencing": 47
  }
}

This enables:

Quick entity type validation without manual triple filtering
Finding all entities of a given type (e.g. "what are all the K8s nodes?")
Detecting when an entity has no type at all (incomplete identity)
Building a type directory for external tools/agents

Relationship to bounded daemon WI (019e480d)

Goal CRUD is a prerequisite for bounded daemon runs — you need to be able to inject a specific goal before running N cycles, then read results after. The goal lifecycle + entity schema exposure together make the MCP interface a complete management surface for the daemon.

2026-05-21 01:10 UTC

Summary

Implement MCP tooling to expose full CRUD lifecycle management for agent goals and querying capabilities for entity schemas. This will allow granular manipulation of daemon states, selective goal prioritization, and easier inspection of triple-based entity relationships.

Approach

First, update the gRPC schema in anima-proto to define the new messages for Goal CRUD (create_goal, update_goal, cancel_goal, prioritize_goals) and Entity Schema exposure (entity_schema, entity_types, entity_type_filter). Next, in anima-core, introduce the expanded domain models for the goal lifecycle (enums for Proposed, Active, Dormant, Completed, Cancelled, Suspended) and structured entity representations. In anima-db, create a SQL migration adding the newly required fields (criteria_text, status, priority, parent_goal_id) to the existing goals table, and write repository methods that can aggregate triple data to extract entity types and relationship provenance. Finally, implement the gRPC service methods in anima-server and register the new MCP tool handlers in the anima-agent daemon, passing commands down to the structured backend and ensuring the OODA loop logic halts or resumes based on the updated goal statuses.

Files likely to change

proto/anima/v1/agent.proto
crates/anima-core/src/domain/agent.rs
crates/anima-db/migrations/005_agent_goals_and_entities.sql (incremented NNN prefix)
crates/anima-db/src/repo/agent.rs
crates/anima-server/src/services/agent.rs
crates/anima-agent/src/mcp.rs (guess)
crates/anima-agent/src/main.rs

Open questions

Should soft-deleted/cancelled goals automatically interrupt executing OODA loops in anima-agent, or just be ignored on the next tick?
Are the episodes mentioned in the provenance summary (e.g., episodes_referencing) already tracked in the active anima-db schema, or does this require new tracking infrastructure?
Does the schema aggregation (filtering outgoing/incoming relations and is-a types) need aggressive caching, or is querying the raw triples table on every MCP tool invocation sufficiently performant?
How exactly is the MCP JSON-RPC layer mapped to the internal services—does anima-agent directly handle the JSON-RPC and proxy to anima-server via gRPC, or does anima-server host the MCP endpoints directly?

Complexity

M: The implementation touches the full stack from database migrations to gRPC definitions and daemon MCP bindings. While CRUD operations are straightforward, constructing the entity schemas from raw graph triples in PostgreSQL will require somewhat complex aggregation queries.

REQUEUE POINTERS (2026-07-23)

Requeued from parked / human-parked (parked since May, 9 prior sessions, all failed, last 2026-05-21).

1. ⚠ THE TRIAGE SECTION ABOVE POINTS AT THE WRONG REPOSITORY. The auto-generated "Approach" and "Files likely to change" list ANIMA paths — proto/anima/v1/agent.proto, crates/anima-core/..., crates/anima-db/..., crates/anima-server/..., crates/anima-agent/.... This is an akh-medu work item; akh-medu is a separate repo (https://code.aopc.cloud/toasterson/akh-medu) with its OWN crates. anima-agent and anima-ai are retired in Anima anyway (ADR 0018). Ignore that file list entirely and locate the real akhomed MCP surface in akh-medu. This mis-generation affects several April/May akh-medu WIs and is a plausible contributor to the repeated failures.

2. This is TWO independent deliverables — land Part 1 first. Part 1 = Goal CRUD MCP tools. Part 2 = entity schema exposure. They share nothing but the MCP registration surface. If the exit bar is tight, split Part 2 into a follow-up WI rather than holding Part 1 hostage.

3. Executor is now tecton (2026-07-23) — the akh works on its own MCP surface and has direct knowledge of agent_goals, list_workspaces, triples_of and the OODA goal lifecycle. Verify the CURRENT live tool surface before trusting this description's inventory; it was written in May.

4. The motivating numbers are stale — "16 active goals, 53 total, 44 cancelled" was observed 2026-05-20. Re-measure before designing cleanup semantics.

5. Implement the lifecycle as written (proposed → active → dormant → completed | cancelled | suspended). It is deliberately richer than Anima's phase axis and unrelated to it — do not try to align the two.

6. If you hit the same wall twice, STOP and report rather than burning turns. This WI was parked because it looped.

Anima work item `019e480e-44e8-7213-b072-bdfacd98af68`. ## Part 1 — Goal CRUD (MCP tools) Currently akhomed exposes `agent_goals` (read-only list) and `list_workspaces`, but there is no way to create, update, suspend, cancel, or delete agent goals through MCP. The agent creates goals autonomously via `infer_rules` / OODA gap detection, and they accumulate indefinitely (16 active goals observed May 20, with 53 total and 44 canceled from prior sessions). ### New MCP tools: - **`create_goal`**: `{workspace, goal_text, criteria_text, priority, parent_goal_id?}` → creates a new goal with explicit criteria - **`update_goal`**: `{workspace, goal_id, goal_text?, criteria_text?, priority?, status?}` → modify existing goal - **`cancel_goal`**: `{workspace, goal_id}` → mark goal as cancelled/archived (soft-delete) - **`prioritize_goals`**: `{workspace, goal_ids: [...], priorities: [...]}` → batch re-prioritize - **`agent_goals`**: extend response to include goal status (active/dormant/cancelled/completed), created_at, cycles_spent, triples_created, parent_goal chain ### Goal lifecycle: ``` proposed → active → dormant → completed → cancelled → suspended ``` This enables: - Surgical cleanup of stuck goals from MCP without restarting akhomed - Explicit goal injection (e.g. "verify Tecton identity against MEMORY.md") - Goal prioritization by priority number - Visibility into which goals are consuming the most OODA cycles ## Part 2 — Entity Schema Exposure Currently entity type information is buried in triples — to find what an entity *is* you have to call `triples_of` and filter for `is-a` relations. There's no MCP-level concept of entity schemas/types. ### New MCP tools: - **`entity_schema`**: `{entity, workspace}` → returns the entity's type hierarchy, outgoing and incoming relation types, confidence scores, and provenance summary - **`entity_types`**: `{workspace}` → list all unique entity types (values of `is-a` relations) with counts - **`entity_type_filter`**: `{workspace, type, page, page_size}` → list all entities of a given type with their core attributes ### Example response for `entity_schema entity=Tecton`: ```json { "entity": "Tecton", "types": ["DigitalArchitect", "First construct and extension of consciousness"], "outgoing_relations": { "member-of": ["Ennead"], "runs-on": ["MacMini"], "works-on": ["akh-medu", "oxifed"], "deity": ["Ptah"], "role": ["Coordinator"] }, "incoming_relations": { "hosts": ["OpenClaw"], "has-member": ["Ennead"] }, "provenance_summary": { "asserted": 14, "derived": 4, "episodes_referencing": 47 } } ``` This enables: - Quick entity type validation without manual triple filtering - Finding all entities of a given type (e.g. "what are all the K8s nodes?") - Detecting when an entity has no type at all (incomplete identity) - Building a type directory for external tools/agents ## Relationship to bounded daemon WI (019e480d) Goal CRUD is a prerequisite for bounded daemon runs — you need to be able to inject a specific goal before running N cycles, then read results after. The goal lifecycle + entity schema exposure together make the MCP interface a complete management surface for the daemon.  2026-05-21 01:10 UTC ## Summary Implement MCP tooling to expose full CRUD lifecycle management for agent goals and querying capabilities for entity schemas. This will allow granular manipulation of daemon states, selective goal prioritization, and easier inspection of triple-based entity relationships. ## Approach First, update the gRPC schema in `anima-proto` to define the new messages for Goal CRUD (`create_goal`, `update_goal`, `cancel_goal`, `prioritize_goals`) and Entity Schema exposure (`entity_schema`, `entity_types`, `entity_type_filter`). Next, in `anima-core`, introduce the expanded domain models for the goal lifecycle (enums for Proposed, Active, Dormant, Completed, Cancelled, Suspended) and structured entity representations. In `anima-db`, create a SQL migration adding the newly required fields (`criteria_text`, `status`, `priority`, `parent_goal_id`) to the existing goals table, and write repository methods that can aggregate triple data to extract entity types and relationship provenance. Finally, implement the gRPC service methods in `anima-server` and register the new MCP tool handlers in the `anima-agent` daemon, passing commands down to the structured backend and ensuring the OODA loop logic halts or resumes based on the updated goal statuses. ## Files likely to change * `proto/anima/v1/agent.proto` * `crates/anima-core/src/domain/agent.rs` * `crates/anima-db/migrations/005_agent_goals_and_entities.sql` (incremented NNN prefix) * `crates/anima-db/src/repo/agent.rs` * `crates/anima-server/src/services/agent.rs` * `crates/anima-agent/src/mcp.rs` (guess) * `crates/anima-agent/src/main.rs` ## Open questions * Should soft-deleted/cancelled goals automatically interrupt executing OODA loops in `anima-agent`, or just be ignored on the next tick? * Are the `episodes` mentioned in the provenance summary (e.g., `episodes_referencing`) already tracked in the active `anima-db` schema, or does this require new tracking infrastructure? * Does the schema aggregation (filtering outgoing/incoming relations and `is-a` types) need aggressive caching, or is querying the raw triples table on every MCP tool invocation sufficiently performant? * How exactly is the MCP JSON-RPC layer mapped to the internal services—does `anima-agent` directly handle the JSON-RPC and proxy to `anima-server` via gRPC, or does `anima-server` host the MCP endpoints directly? ## Complexity M: The implementation touches the full stack from database migrations to gRPC definitions and daemon MCP bindings. While CRUD operations are straightforward, constructing the entity schemas from raw graph triples in PostgreSQL will require somewhat complex aggregation queries. --- ## REQUEUE POINTERS (2026-07-23) Requeued from `parked` / `human-parked` (parked since May, 9 prior sessions, all failed, last 2026-05-21). **1. ⚠ THE TRIAGE SECTION ABOVE POINTS AT THE WRONG REPOSITORY.** The auto-generated "Approach" and "Files likely to change" list ANIMA paths — `proto/anima/v1/agent.proto`, `crates/anima-core/...`, `crates/anima-db/...`, `crates/anima-server/...`, `crates/anima-agent/...`. This is an **akh-medu** work item; akh-medu is a separate repo (https://code.aopc.cloud/toasterson/akh-medu) with its OWN crates. `anima-agent` and `anima-ai` are retired in Anima anyway (ADR 0018). **Ignore that file list entirely** and locate the real akhomed MCP surface in akh-medu. This mis-generation affects several April/May akh-medu WIs and is a plausible contributor to the repeated failures. **2. This is TWO independent deliverables — land Part 1 first.** Part 1 = Goal CRUD MCP tools. Part 2 = entity schema exposure. They share nothing but the MCP registration surface. If the exit bar is tight, split Part 2 into a follow-up WI rather than holding Part 1 hostage. **3. Executor is now `tecton`** (2026-07-23) — the akh works on its own MCP surface and has direct knowledge of `agent_goals`, `list_workspaces`, `triples_of` and the OODA goal lifecycle. Verify the CURRENT live tool surface before trusting this description's inventory; it was written in May. **4. The motivating numbers are stale** — "16 active goals, 53 total, 44 cancelled" was observed 2026-05-20. Re-measure before designing cleanup semantics. **5. Implement the lifecycle as written** (`proposed → active → dormant → completed | cancelled | suspended`). It is deliberately richer than Anima's phase axis and unrelated to it — do not try to align the two. **6. If you hit the same wall twice, STOP and report** rather than burning turns. This WI was parked because it looped.

toasterson added 2 commits

2026-08-04 16:09:51 +00:00