Control gRPC API

Current public MuBit ControlService RPC surface for memory, diagnostics, learning loop, coordination, and explicit planning state.

This page summarizes the current public mubit.v1.ControlService RPC surface. Use it for generated-client debugging and transport-parity checks.

Service identity

• Package: mubit.v1
• Service: ControlService

Core memory RPCs

MAS and learning-loop RPCs

Managed resources: Projects, Agents, Skills, Prompts

Managed MuBit deployments version agent configuration server-side so prompt + skill changes can be reviewed, rolled out, and rolled back without touching deployed SDK code.

PromptVersion / SkillVersion lifecycle

Both prompt and skill versions share the same state machine:

• status transitions: candidate → active (via ActivatePromptVersion / ActivateSkillVersion) → retired (when a newer version becomes active) → archived.
• source values: manual (written via SetPrompt / CreateSkill), optimization (minted by OptimizePrompt / OptimizeSkill), rollback (restored from a retired version).
• Each version carries outcome aggregates: avg_outcome_score, outcome_count, and optimization_summary.

OptimizePrompt and OptimizeSkill accept an optional LlmOverride (provider, model, temperature, max_tokens, timeout_ms) so you can steer which model synthesises the candidate.

GetPromptDiff / GetSkillDiff return a unified diff_text comparing any two versions — the same text the console surfaces in its review UI.

Deprecated planning state RPCs

The following RPCs remain wired for backward compatibility but are no longer the recommended path. Use external task/orchestration systems (Linear, Jira, LangGraph, CrewAI) for goals, actions, and decision cycles. See State management endpoints for guidance.

Practical parity checks

• Helper-first SDKs should map cleanly onto these RPC groups even when they expose more ergonomic names.
• GetContext is the primary gRPC compaction-safe context assembly surface.
• ListActivity and ExportActivity are the chronological audit/browse surfaces; use them when you need exact ordering and pagination rather than ranked retrieval.
• Diagnose, GetMemoryHealth, Reflect, RecordOutcome, RecordStepOutcome, and SurfaceStrategies are the key loop-inspection and reinforcement RPCs.
• RecordStepOutcome records per-step process rewards with signal, rationale, and directive hint for dense RL within a run.
• Reflect accepts step_id, last_n_items, and include_step_outcomes for step-wise scoped reflection.
• Ingest, Query, and GetContext accept lane fields (lane, lane_filter) for multi-agent memory isolation within a shared run.
• ArchiveBlock and Dereference are the exact-reference pair: archive an exact artifact once, then recover it later by stable reference_id.

Evidence provenance and telemetry

Query and GetContext now expose exact-reference provenance on surfaced evidence:

• retrieval_mode
• reference_id
• referenceable
• origin_entry_type

AgentQueryResponse also returns a citations field (repeated uint32, field 9) — 0-based indices into evidence marking which items grounded final_answer (empty when the answer cites no specific evidence). The indices are validated server-side against the evidence length, so every value is a valid index into evidence.

GetContext also returns context-pressure telemetry:

• source counts by entry type and retrieval mode
• evidence candidates considered
• evidence dropped by token budget
• exact references surfaced

Step-level outcomes

RecordStepOutcome records a per-step process reward signal within a run, complementing the run-level RecordOutcome. Use it after each agentic step where you want dense feedback for reflection.

Response returns step_outcome_id and accepted. Emits context.step_outcome_recorded event.

Run-level outcome attribution

RecordOutcomeRequest carries two fields for accurate, idempotent reinforcement:

Lane-scoped memory

Lanes partition memory within a shared run so each agent sees only relevant entries.

Items without a lane are visible to all queries. Items with a lane are visible only when lane_filter matches or is empty.

Failure modes and troubleshooting

Next steps

• Review HTTP route names at Control HTTP reference.
• Review the helper-first SDK surfaces at SDK methods.