HR¶

async def register(self, identity: AgentIdentity) -> None:
    """Register a new agent.

    Args:
        identity: The agent identity to register.

    Raises:
        AgentAlreadyRegisteredError: If the agent is already registered.
    """
    agent_key = str(identity.id)
    async with self._lock:
        if agent_key in self._agents:
            msg = f"Agent {identity.name!r} ({agent_key}) is already registered"
            logger.warning(
                HR_REGISTRY_AGENT_REGISTERED,
                agent_id=agent_key,
                error=msg,
            )
            raise AgentAlreadyRegisteredError(msg)
        self._agents[agent_key] = identity

    logger.info(
        HR_REGISTRY_AGENT_REGISTERED,
        agent_id=agent_key,
        agent_name=str(identity.name),
        status=identity.status.value,
    )

async def unregister(self, agent_id: NotBlankStr) -> AgentIdentity:
    """Remove an agent from the registry.

    Args:
        agent_id: The agent identifier to remove.

    Returns:
        The removed agent identity.

    Raises:
        AgentNotFoundError: If the agent is not found.
    """
    async with self._lock:
        identity = self._agents.pop(str(agent_id), None)
    if identity is None:
        msg = f"Agent {agent_id!r} not found in registry"
        logger.warning(
            HR_REGISTRY_AGENT_REMOVED,
            agent_id=str(agent_id),
            error=msg,
        )
        raise AgentNotFoundError(msg)

    logger.info(
        HR_REGISTRY_AGENT_REMOVED,
        agent_id=str(agent_id),
        agent_name=str(identity.name),
    )
    return identity

async def get(self, agent_id: NotBlankStr) -> AgentIdentity | None:
    """Retrieve an agent identity by ID.

    Args:
        agent_id: The agent identifier.

    Returns:
        The agent identity, or None if not found.
    """
    async with self._lock:
        return self._agents.get(str(agent_id))

async def get_by_name(self, name: NotBlankStr) -> AgentIdentity | None:
    """Retrieve an agent identity by name.

    Args:
        name: The agent name to search for.

    Returns:
        The first matching agent, or None.
    """
    async with self._lock:
        name_lower = str(name).lower()
        for identity in self._agents.values():
            if str(identity.name).lower() == name_lower:
                return identity
        return None

async def list_active(self) -> tuple[AgentIdentity, ...]:
    """List all agents with ACTIVE status.

    Returns:
        Tuple of active agent identities.
    """
    async with self._lock:
        return tuple(
            a for a in self._agents.values() if a.status == AgentStatus.ACTIVE
        )

async def list_by_department(
    self,
    department: NotBlankStr,
) -> tuple[AgentIdentity, ...]:
    """List agents in a specific department.

    Args:
        department: Department name to filter by.

    Returns:
        Tuple of matching agent identities.
    """
    async with self._lock:
        dept_lower = str(department).lower()
        return tuple(
            a
            for a in self._agents.values()
            if str(a.department).lower() == dept_lower
        )

async def update_status(
    self,
    agent_id: NotBlankStr,
    status: AgentStatus,
) -> AgentIdentity:
    """Update an agent's lifecycle status.

    Args:
        agent_id: The agent identifier.
        status: New status.

    Returns:
        Updated agent identity.

    Raises:
        AgentNotFoundError: If the agent is not found.
    """
    key = str(agent_id)
    async with self._lock:
        identity = self._agents.get(key)
        if identity is None:
            msg = f"Agent {agent_id!r} not found in registry"
            logger.warning(
                HR_REGISTRY_STATUS_UPDATED,
                agent_id=key,
                error=msg,
            )
            raise AgentNotFoundError(msg)
        updated = identity.model_copy(update={"status": status})
        self._agents[key] = updated

    logger.info(
        HR_REGISTRY_STATUS_UPDATED,
        agent_id=key,
        status=status.value,
    )
    return updated

async def update_identity(
    self,
    agent_id: NotBlankStr,
    **updates: Any,
) -> AgentIdentity:
    """Update agent identity fields via model_copy(update=...).

    Only fields in ``_UPDATABLE_FIELDS`` are accepted.  Use
    ``update_status`` for status changes.

    Args:
        agent_id: The agent identifier.
        **updates: Fields to update on the AgentIdentity.

    Returns:
        Updated agent identity.

    Raises:
        AgentNotFoundError: If the agent is not found.
        ValueError: If any field is not in the allowlist.
    """
    disallowed = set(updates.keys()) - self._UPDATABLE_FIELDS
    if disallowed:
        msg = (
            f"Fields not allowed for update_identity: "
            f"{sorted(disallowed)}; allowed: {sorted(self._UPDATABLE_FIELDS)}"
        )
        logger.warning(
            HR_REGISTRY_IDENTITY_UPDATED,
            agent_id=str(agent_id),
            error=msg,
        )
        raise ValueError(msg)

    key = str(agent_id)
    async with self._lock:
        identity = self._agents.get(key)
        if identity is None:
            msg = f"Agent {agent_id!r} not found in registry"
            logger.warning(
                HR_REGISTRY_IDENTITY_UPDATED,
                agent_id=key,
                error=msg,
            )
            raise AgentNotFoundError(msg)
        updated = identity.model_copy(update=updates)
        self._agents[key] = updated

    logger.info(
        HR_REGISTRY_IDENTITY_UPDATED,
        agent_id=key,
        updated_fields=sorted(updates.keys()),
    )
    return updated

async def agent_count(self) -> int:
    """Number of agents currently in the registry."""
    async with self._lock:
        return len(self._agents)

async def create_request(  # noqa: PLR0913
    self,
    *,
    requested_by: NotBlankStr,
    department: NotBlankStr,
    role: NotBlankStr,
    level: str,
    required_skills: tuple[NotBlankStr, ...] = (),
    reason: NotBlankStr,
    budget_limit_monthly: float | None = None,
    template_name: str | None = None,
) -> HiringRequest:
    """Create a new hiring request.

    Args:
        requested_by: Request initiator.
        department: Target department.
        role: Desired role.
        level: Desired seniority level.
        required_skills: Required skills.
        reason: Business justification.
        budget_limit_monthly: Optional monthly budget limit.
        template_name: Template for candidate generation.

    Returns:
        The created hiring request.
    """
    try:
        parsed_level = SeniorityLevel(level)
    except ValueError as exc:
        msg = f"Invalid seniority level {level!r} for hiring request"
        logger.warning(
            HR_HIRING_REQUEST_CREATED,
            error=msg,
            level=level,
        )
        raise HiringError(msg) from exc

    request = HiringRequest(
        requested_by=requested_by,
        department=department,
        role=role,
        level=parsed_level,
        required_skills=required_skills,
        reason=reason,
        budget_limit_monthly=budget_limit_monthly,
        template_name=template_name,
        created_at=datetime.now(UTC),
    )
    self._requests[str(request.id)] = request

    logger.info(
        HR_HIRING_REQUEST_CREATED,
        request_id=str(request.id),
        department=str(department),
        role=str(role),
    )
    return request

async def generate_candidate(
    self,
    request: HiringRequest,
) -> HiringRequest:
    """Generate a candidate card for a hiring request.

    Builds a ``CandidateCard`` from role/level defaults. In the
    future, this can be extended with template presets and LLM
    customization.

    Args:
        request: The hiring request to generate a candidate for.

    Returns:
        Updated request with the new candidate appended.
    """
    request = self._get_request(str(request.id))

    candidate = CandidateCard(
        name=NotBlankStr(f"{request.role}-{request.department}-agent"),
        role=request.role,
        department=request.department,
        level=request.level,
        skills=request.required_skills,
        rationale=NotBlankStr(
            f"Generated for: {request.reason}",
        ),
        estimated_monthly_cost=(
            request.budget_limit_monthly
            if request.budget_limit_monthly is not None
            else 50.0
        ),
        template_source=request.template_name,
    )

    updated = request.model_copy(
        update={"candidates": (*request.candidates, candidate)},
    )
    self._requests[str(updated.id)] = updated

    logger.info(
        HR_HIRING_CANDIDATE_GENERATED,
        request_id=str(request.id),
        candidate_id=str(candidate.id),
    )
    return updated

async def submit_for_approval(
    self,
    request: HiringRequest,
    candidate_id: str,
) -> HiringRequest:
    """Submit a candidate for approval.

    If no approval store is configured, auto-approves the request.

    Args:
        request: The hiring request.
        candidate_id: ID of the candidate to approve.

    Returns:
        Updated request with approval status.

    Raises:
        InvalidCandidateError: If the candidate ID is not found.
    """
    request = self._get_request(str(request.id))

    candidate = next(
        (c for c in request.candidates if str(c.id) == candidate_id),
        None,
    )
    if candidate is None:
        msg = f"Candidate {candidate_id!r} not found on request {request.id!r}"
        logger.warning(
            HR_HIRING_APPROVAL_SUBMITTED,
            request_id=str(request.id),
            error=msg,
        )
        raise InvalidCandidateError(msg)

    if self._approval_store is None:
        # Auto-approve when no approval store.
        updated = request.model_copy(
            update={
                "status": HiringRequestStatus.APPROVED,
                "selected_candidate_id": candidate_id,
            },
        )
    else:
        # Create an approval item.
        updated = await self._submit_approval_item(request, candidate, candidate_id)

    self._requests[str(updated.id)] = updated

    logger.info(
        HR_HIRING_APPROVAL_SUBMITTED,
        request_id=str(request.id),
        candidate_id=candidate_id,
        auto_approved=self._approval_store is None,
    )
    return updated

async def instantiate_agent(
    self,
    request: HiringRequest,
) -> AgentIdentity:
    """Instantiate an agent from an approved hiring request.

    Args:
        request: The approved hiring request.

    Returns:
        The newly created agent identity.

    Raises:
        HiringApprovalRequiredError: If request is not approved.
        HiringRejectedError: If request was rejected.
        InvalidCandidateError: If no candidate is selected.
        HiringError: If instantiation fails.
    """
    request = self._get_request(str(request.id))
    self._validate_instantiation_status(request)
    candidate = self._find_selected_candidate(request)

    identity = self._build_agent_identity(candidate)
    await self._register_agent(identity, request)

    # Update request status.
    updated = request.model_copy(
        update={"status": HiringRequestStatus.INSTANTIATED},
    )
    self._requests[str(updated.id)] = updated

    # Start onboarding if service is available.
    await self._try_onboard(identity)

    logger.info(
        HR_HIRING_INSTANTIATED,
        request_id=str(request.id),
        agent_id=str(identity.id),
        agent_name=str(identity.name),
    )
    return identity

async def start_onboarding(self, agent_id: str) -> OnboardingChecklist:
    """Start onboarding for a newly hired agent.

    Creates a checklist with all onboarding steps in PENDING state.

    Args:
        agent_id: Agent to onboard.

    Returns:
        The created onboarding checklist.

    Raises:
        OnboardingError: If a checklist already exists.
    """
    agent = await self._registry.get(NotBlankStr(agent_id))
    if agent is None:
        msg = f"Agent {agent_id!r} not found in registry"
        logger.warning(HR_ONBOARDING_STARTED, agent_id=agent_id, error=msg)
        raise OnboardingError(msg)

    if agent_id in self._checklists:
        msg = f"Onboarding checklist already exists for agent {agent_id!r}"
        logger.warning(HR_ONBOARDING_STARTED, agent_id=agent_id, error=msg)
        raise OnboardingError(msg)

    steps = tuple(OnboardingStepRecord(step=step) for step in OnboardingStep)
    checklist = OnboardingChecklist(
        agent_id=agent_id,
        steps=steps,
        started_at=datetime.now(UTC),
    )
    self._checklists[agent_id] = checklist

    logger.info(
        HR_ONBOARDING_STARTED,
        agent_id=agent_id,
        step_count=len(steps),
    )
    return checklist

async def complete_step(
    self,
    agent_id: str,
    step: OnboardingStep,
    *,
    notes: str = "",
) -> OnboardingChecklist:
    """Mark an onboarding step as complete.

    When all steps are completed, automatically transitions the
    agent to ACTIVE status.

    Args:
        agent_id: Agent being onboarded.
        step: The step to complete.
        notes: Optional notes for the step.

    Returns:
        Updated onboarding checklist.

    Raises:
        OnboardingError: If no checklist exists for the agent.
    """
    checklist = self._checklists.get(agent_id)
    if checklist is None:
        msg = f"No onboarding checklist for agent {agent_id!r}"
        logger.warning(
            HR_ONBOARDING_STEP_COMPLETE,
            agent_id=agent_id,
            error=msg,
        )
        raise OnboardingError(msg)

    now = datetime.now(UTC)
    step_found = any(s.step == step and not s.completed for s in checklist.steps)
    if not step_found:
        logger.warning(
            HR_ONBOARDING_STEP_COMPLETE,
            agent_id=agent_id,
            step=step.value,
            skipped="step_not_found_or_already_completed",
        )
        return checklist

    updated_steps = tuple(
        s.model_copy(
            update={
                "completed": True,
                "completed_at": now,
                "notes": notes,
            },
        )
        if s.step == step and not s.completed
        else s
        for s in checklist.steps
    )

    updated = checklist.model_copy(update={"steps": updated_steps})

    # Check if all steps are now complete.
    if updated.is_complete and not checklist.is_complete:
        updated = updated.model_copy(update={"completed_at": now})
        await self._registry.update_status(agent_id, AgentStatus.ACTIVE)
        logger.info(HR_ONBOARDING_COMPLETE, agent_id=agent_id)

    self._checklists[agent_id] = updated

    logger.info(
        HR_ONBOARDING_STEP_COMPLETE,
        agent_id=agent_id,
        step=step.value,
    )
    return updated