Типизированный вызов сценария

CodeGraph экспортирует один типизированный Python-контракт для role-bound выполнения сценария. Он подходит для внутрипроцессной интеграции, уже связанной с управляемой задачей CodeGraph. Агентскому или удалённому клиенту следует использовать зарегистрированную MCP/API-поверхность, а не импортировать внутренние модули репозитория.

Минимальный запрос

from src.digital_employees.runtime.scenarios import (
    RoleBoundScenarioInvocationRequest,
    invoke_role_bound_scenario_request,
)

request = RoleBoundScenarioInvocationRequest(
    query="Обнови документацию интерфейса для выбранной задачи.",
    context={
        "project_key": "codegraph",
        "namespace": "default",
        "task_id": "<task-id>",
        "source_refs": ["source://current-contract"],
    },
    employee_id="codegraph_docs",
    scenario_id="scenario_03",
    event_type="docs_memory_sync_start",
    execution_source="customer_in_process_integration",
)

result = invoke_role_bound_scenario_request(request)

Пример намеренно связан с сотрудником документации и его сценарием. Другой сценарий допустим только тогда, когда это разрешено политикой сотрудника и carrier задачи.

Обязательный контекст управления

Объект запроса проверяет три поля context:

• project_key — зарегистрированный проект CodeGraph;
• namespace — его пространство имён;
• task_id — активная task capsule, к которой относится работа.

При неполной области вызов закрывается с ошибкой role_bound_scenario_contract_missing:<fields>. Затем runtime разрешает или проверяет ответственного employee_id, его право на сценарий, строит evidence вызова и выполняет preflight. Поэтому синтаксически правильный запрос тоже может быть отклонён.

Нельзя перехватывать governance-ошибку и повторять операцию через низкоуровневый handler. Восстановите carrier, policy, event или отсутствующее evidence.

Поля запроса

Если scenario_id не задан, runtime классифицирует запрос. Для воспроизводимой автоматизации обычно лучше явный идентификатор: так сохраняется назначенная lane и проще диагностируется отказ policy.

Контракт результата

Возвращается словарь выбранного сценария. Role-bound wrapper добавляет общие поля:

• scenario_id — канонический выбранный сценарий;
• intent — связанное с ним намерение;
• classification_method — способ выбора;
• metadata.role_bound_scenario_invocation — сотрудник, событие, источник выполнения, workflow, ссылка evidence и статус preflight;
• metadata.scenario_invocation_evidence — полный объект evidence вызова.

Специфичные поля сценариев различаются. Сначала проверяйте общую оболочку, затем — поля конкретного сценария. Нельзя предполагать единые недокументированные поля answer, sources или confidence для всех workflow.

Обработка ошибок

Считайте стабильный префикс категорией, но сохраняйте полное сообщение в диагностике:

• role_bound_scenario_contract_missing — нет обязательной области задачи;
• role_bound_scenario_preflight_failed — preflight события или evidence не готов;
• role_bound_employee_not_allowed_for_scenario — employee и scenario несовместимы;
• role_bound_scenario_retired — сценарий выведен из эксплуатации;
• role_bound_scenario_not_registered — handler workflow не зарегистрирован.

Пример обработки на границе интеграции:

try:
    result = invoke_role_bound_scenario_request(request)
except RuntimeError as exc:
    if str(exc).startswith("role_bound_"):
        raise IntegrationError(f"CodeGraph отклонил сценарий: {exc}") from exc
    raise

Не подставляйте другой сценарий молча. Выбранная история, сотрудник и evidence lane являются частью смысла операции.

Конкурентность и побочные эффекты

Для вызывающего кода операция синхронна. Выбранный workflow может обращаться к сервисам проекта или формировать управляемое evidence. Если вызов способен блокировать, не выполняйте его в основном потоке async event loop. Для долговечного удалённого выполнения используйте orchestration-поверхность вашей установки.

Типизированный запрос не даёт права на произвольное редактирование файлов, публикацию или изменение состояния. Для таких действий по-прежнему нужны carrier задачи, владелец lane и approvals соответствующего контракта.

Поддерживаемые источники

• src/digital_employees/runtime/scenarios/__init__.py определяет экспортируемые имена.
• src/digital_employees/runtime/scenarios/role_bound_scenario_invoker.py определяет проверку запроса, маршрутизацию и общую оболочку результата.
• src/digital_employees/runtime/scenarios/employee_scenario_invocation.py определяет employee/scenario/event policy и evidence вызова.

При расхождении с установленной ревизией авторитетен экспортируемый контракт исходного кода.