newbro-cli 0.1.0__py3-none-any.whl

synapse/api/models.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from synapse.observability.schema import DiagnosticEvent
+from synapse.protocol import ExecutorNodeCredentialIssue, ExecutorNodeRecord, TaskCommandType
+from synapse.runtime.models import SessionSnapshot
+
+
+class SessionResponse(BaseModel):
+    session_id: str
+
+
+class MessageRequest(BaseModel):
+    text: str
+    source: Literal["user", "connector"] = "user"
+
+
+class ToolInvocationSummary(BaseModel):
+    tool_name: str
+    args: dict[str, object] = Field(default_factory=dict)
+
+
+class MessageResponse(BaseModel):
+    message_id: str
+    reply_text: str
+    conversational_act: str
+    affected_task_ids: list[str] = Field(default_factory=list)
+    tool_invocations: list[ToolInvocationSummary] = Field(default_factory=list)
+
+
+class CommandRequest(BaseModel):
+    command_type: TaskCommandType
+    task_id: str | None = None
+    reference: str | None = None
+    payload: dict[str, object] = Field(default_factory=dict)
+    reason: str | None = None
+
+
+class CommandResponse(BaseModel):
+    command_id: str
+    status: str = "accepted"
+    affected_task_ids: list[str] = Field(default_factory=list)
+
+
+class ResolveInteractionRequest(BaseModel):
+    action: Literal["approve", "deny", "answer", "confirm", "cancel"]
+    answer_text: str | None = None
+    option_id: str | None = None
+    reason: str | None = None
+
+
+class ResolveInteractionRequestResponse(BaseModel):
+    request_id: str
+    status: str = "accepted"
+    affected_task_ids: list[str] = Field(default_factory=list)
+
+
+class SendMessageSocketAction(BaseModel):
+    type: Literal["send_message"] = "send_message"
+    request_id: str
+    text: str
+    source: Literal["user", "connector"] = "user"
+    target_persona_id: str | None = None
+
+
+class SendCommandSocketAction(BaseModel):
+    type: Literal["send_command"] = "send_command"
+    request_id: str
+    command_type: TaskCommandType
+    task_id: str | None = None
+    reference: str | None = None
+    payload: dict[str, object] = Field(default_factory=dict)
+    reason: str | None = None
+
+
+class ResolveInteractionRequestSocketAction(BaseModel):
+    type: Literal["resolve_interaction_request"] = "resolve_interaction_request"
+    request_id: str
+    interaction_request_id: str
+    action: Literal["approve", "deny", "answer", "confirm", "cancel"]
+    answer_text: str | None = None
+    option_id: str | None = None
+    reason: str | None = None
+
+
+class DiagnosticTimelineResponse(BaseModel):
+    events: list[DiagnosticEvent] = Field(default_factory=list)
+
+
+class PersonaCreateRequest(BaseModel):
+    name: str
+    avatar: str = ""
+    base_prompt: str = ""
+    executor_node_id: str | None = None
+
+
+class PersonaUpdateRequest(BaseModel):
+    name: str | None = None
+    avatar: str | None = None
+    base_prompt: str | None = None
+    executor_node_id: str | None = None
+
+
+class ExecutorNodeCreateRequest(BaseModel):
+    name: str
+    enabled_executors: list[str] = Field(default_factory=list)
+
+
+class ExecutorNodeUpdateRequest(BaseModel):
+    name: str | None = None
+    enabled_executors: list[str] | None = None
+
+
+__all__ = [
+    "CommandRequest",
+    "CommandResponse",
+    "DiagnosticTimelineResponse",
+    "ExecutorNodeCreateRequest",
+    "ExecutorNodeCredentialIssue",
+    "ExecutorNodeRecord",
+    "ExecutorNodeUpdateRequest",
+    "MessageRequest",
+    "MessageResponse",
+    "ResolveInteractionRequest",
+    "ResolveInteractionRequestResponse",
+    "ResolveInteractionRequestSocketAction",
+    "SendCommandSocketAction",
+    "SendMessageSocketAction",
+    "SessionResponse",
+    "SessionSnapshot",
+    "ToolInvocationSummary",
+]

synapse/api/paths.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+API_PREFIX = "/api"
+
+# Keep legacy API-like prefixes reserved in the combined service so the SPA
+# never claims old API URLs after the hard cutover to /api.
+LEGACY_API_ROUTE_PREFIXES = {
+    "health",
+    "sessions",
+    "messages",
+    "commands",
+    "interaction-requests",
+    "personas",
+    "executors",
+    "connectors",
+    "openapi.json",
+    "docs",
+    "redoc",
+}
+
+SERVICE_RESERVED_ROUTE_PREFIXES = {"api", *LEGACY_API_ROUTE_PREFIXES}
+
+
+def api_path(path: str) -> str:
+    normalized = path if path.startswith("/") else f"/{path}"
+    return f"{API_PREFIX}{normalized}"

synapse/api/routes/__init__.py

@@ -0,0 +1 @@
+"""HTTP routes for the new Synapse API."""

synapse/api/routes/commands.py

@@ -0,0 +1,66 @@
+from uuid import uuid4
+
+from fastapi import APIRouter, HTTPException, Request
+
+from synapse.api.models import CommandRequest, CommandResponse
+from synapse.communication.resolver import TaskResolver, describe_candidates
+from synapse.observability.context import bind_diagnostic_context
+from synapse.protocol import TaskCommand
+
+router = APIRouter()
+
+
+@router.post("/sessions/{session_id}/commands", response_model=CommandResponse)
+async def submit_command(
+    session_id: str,
+    request: CommandRequest,
+    http_request: Request,
+) -> CommandResponse:
+    container = http_request.app.state.runtime_container
+    try:
+        session = container.get_session(session_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+
+    tasks = await session.blackboard.list_tasks()
+    resolution = TaskResolver().resolve(tasks, task_id=request.task_id, reference=request.reference)
+    if resolution.status == "ambiguous":
+        raise HTTPException(
+            status_code=409,
+            detail=(
+                "Task reference is ambiguous. Relevant tasks: "
+                f"{describe_candidates(resolution.candidates)}."
+            ),
+        )
+    task = resolution.task
+    if task is None:
+        raise HTTPException(status_code=404, detail="Task not found.")
+    validation_error = await session.validate_task_command(task, request.command_type)
+    if validation_error is not None:
+        raise HTTPException(status_code=409, detail=validation_error)
+
+    command = TaskCommand(
+        command_id=f"cmd-{uuid4().hex[:8]}",
+        task_id=task.task_id,
+        command_type=request.command_type,
+        payload=request.payload,
+        created_by="api",
+        reason=request.reason,
+    )
+    request_id = f"http-cmd-{uuid4().hex[:8]}"
+    session.observability.api.command_accepted(
+        conversation_id=session.session_id,
+        request_id=request_id,
+        task_id=task.task_id,
+        command_type=request.command_type.value,
+        transport="http",
+    )
+    with bind_diagnostic_context(
+        conversation_id=session.session_id,
+        request_id=request_id,
+        task_id=task.task_id,
+    ):
+        await session.apply_command(command)
+    session.schedule_execution()
+    await session.publish_snapshot()
+    return CommandResponse(command_id=command.command_id, affected_task_ids=[task.task_id])

synapse/api/routes/executor_nodes.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException, Request
+
+from synapse.api.models import ExecutorNodeCreateRequest, ExecutorNodeUpdateRequest
+
+router = APIRouter()
+
+
+def _require_session(container, session_id: str):
+    try:
+        return container.get_session(session_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+
+
+@router.get("/sessions/{session_id}/executor-nodes")
+async def list_executor_nodes(session_id: str, request: Request):
+    container = request.app.state.runtime_container
+    _require_session(container, session_id)
+    return await container.executor_node_manager.list_nodes()
+
+
+@router.post("/sessions/{session_id}/executor-nodes", status_code=201)
+async def create_executor_node(
+    session_id: str,
+    body: ExecutorNodeCreateRequest,
+    request: Request,
+):
+    container = request.app.state.runtime_container
+    _require_session(container, session_id)
+    try:
+        issue = await container.executor_node_manager.create_node(
+            name=body.name,
+            enabled_executors=body.enabled_executors,
+        )
+    except RuntimeError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    await container.publish_session_snapshots()
+    return issue
+
+
+@router.patch("/sessions/{session_id}/executor-nodes/{node_id}")
+async def update_executor_node(
+    session_id: str,
+    node_id: str,
+    body: ExecutorNodeUpdateRequest,
+    request: Request,
+):
+    container = request.app.state.runtime_container
+    _require_session(container, session_id)
+    try:
+        record = await container.executor_node_manager.update_node(
+            node_id,
+            name=body.name if "name" in body.model_fields_set else None,
+            enabled_executors=body.enabled_executors if "enabled_executors" in body.model_fields_set else None,
+        )
+    except RuntimeError as exc:
+        detail = str(exc)
+        status_code = 404 if "not found" in detail.lower() else 400
+        raise HTTPException(status_code=status_code, detail=detail) from exc
+    await container.publish_session_snapshots()
+    return record
+
+
+@router.post("/sessions/{session_id}/executor-nodes/{node_id}/credentials/rotate")
+async def rotate_executor_node_credentials(
+    session_id: str,
+    node_id: str,
+    request: Request,
+):
+    container = request.app.state.runtime_container
+    _require_session(container, session_id)
+    try:
+        issue = await container.executor_node_manager.rotate_node_credentials(node_id)
+    except RuntimeError as exc:
+        detail = str(exc)
+        status_code = 404 if "not found" in detail.lower() else 400
+        raise HTTPException(status_code=status_code, detail=detail) from exc
+    await container.publish_session_snapshots()
+    return issue
+
+
+@router.post("/sessions/{session_id}/executor-nodes/{node_id}/connect-command")
+async def reveal_executor_node_connect_command(
+    session_id: str,
+    node_id: str,
+    request: Request,
+):
+    container = request.app.state.runtime_container
+    _require_session(container, session_id)
+    try:
+        issue = await container.executor_node_manager.reveal_node_credentials(node_id)
+    except RuntimeError as exc:
+        detail = str(exc)
+        lowered = detail.lower()
+        if "not found" in lowered:
+            status_code = 404
+        elif "rotate credentials first" in lowered or "legacy non-retrievable" in lowered:
+            status_code = 409
+        else:
+            status_code = 400
+        raise HTTPException(status_code=status_code, detail=detail) from exc
+    return issue
+
+
+@router.delete("/sessions/{session_id}/executor-nodes/{node_id}")
+async def delete_executor_node(
+    session_id: str,
+    node_id: str,
+    request: Request,
+):
+    container = request.app.state.runtime_container
+    _require_session(container, session_id)
+    bound_personas = await container.bound_persona_names_for_node(node_id)
+    if bound_personas:
+        raise HTTPException(
+            status_code=409,
+            detail=f"Executor node '{node_id}' is still bound to bros: {', '.join(bound_personas)}.",
+        )
+    deleted = await container.executor_node_manager.delete_node(node_id)
+    if not deleted:
+        raise HTTPException(status_code=404, detail=f"Executor node '{node_id}' not found.")
+    await container.publish_session_snapshots()
+    return {"deleted": node_id}

synapse/api/routes/health.py

@@ -0,0 +1,8 @@
+from fastapi import APIRouter
+
+router = APIRouter()
+
+
+@router.get("/health")
+async def health() -> dict[str, str]:
+    return {"status": "ok"}

synapse/api/routes/interaction_requests.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, HTTPException, Request
+
+from synapse.api.models import ResolveInteractionRequest, ResolveInteractionRequestResponse
+from synapse.observability.context import bind_diagnostic_context
+
+router = APIRouter()
+LOGGER = logging.getLogger(__name__)
+
+
+@router.post(
+    "/sessions/{session_id}/interaction-requests/{request_id}/resolve",
+    response_model=ResolveInteractionRequestResponse,
+)
+async def resolve_interaction_request(
+    session_id: str,
+    request_id: str,
+    request: ResolveInteractionRequest,
+    http_request: Request,
+) -> ResolveInteractionRequestResponse:
+    container = http_request.app.state.runtime_container
+    try:
+        session = container.get_session(session_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+
+    with bind_diagnostic_context(
+        conversation_id=session.session_id,
+        request_id=f"http-ireq-{request_id}",
+    ):
+        try:
+            affected_task_ids = await session.resolve_interaction_request(
+                request_id,
+                action=request.action,
+                answer_text=request.answer_text,
+                option_id=request.option_id,
+                reason=request.reason,
+            )
+        except KeyError as exc:
+            raise HTTPException(status_code=404, detail=str(exc)) from exc
+        except ValueError as exc:
+            raise HTTPException(status_code=409, detail=str(exc)) from exc
+        try:
+            session.schedule_execution()
+            await session.publish_snapshot()
+        except Exception:
+            LOGGER.warning(
+                "Resolved interaction request %s in session %s, but follow-up scheduling failed.",
+                request_id,
+                session_id,
+                exc_info=True,
+            )
+    return ResolveInteractionRequestResponse(
+        request_id=request_id,
+        affected_task_ids=affected_task_ids,
+    )

synapse/api/routes/messages.py

@@ -0,0 +1,46 @@
+from uuid import uuid4
+
+from fastapi import APIRouter, HTTPException, Request
+
+from synapse.api.models import MessageRequest, MessageResponse, ToolInvocationSummary
+
+router = APIRouter()
+
+
+@router.post("/sessions/{session_id}/messages", response_model=MessageResponse)
+async def submit_message(
+    session_id: str,
+    request: MessageRequest,
+    http_request: Request,
+) -> MessageResponse:
+    container = http_request.app.state.runtime_container
+    try:
+        session = container.get_session(session_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+
+    request_id = f"http-msg-{uuid4().hex[:8]}"
+    _, completion = await session.submit_message(
+        request_id,
+        request.text,
+        source=request.source,
+        start_processing=False,
+    )
+    session.observability.api.message_accepted(
+        conversation_id=session.session_id,
+        request_id=request_id,
+        transport="http",
+    )
+    await session.publish_snapshot()
+    session.start_message_processing()
+    result = await completion
+    return MessageResponse(
+        message_id=result.message_id,
+        reply_text=result.reply_text,
+        conversational_act=result.conversational_act,
+        affected_task_ids=result.affected_task_ids,
+        tool_invocations=[
+            ToolInvocationSummary(tool_name=item.tool_name, args=item.args)
+            for item in result.tool_invocations
+        ],
+    )

synapse/api/routes/personas.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from uuid import uuid4
+
+from fastapi import APIRouter, HTTPException, Request
+
+from synapse.api.models import PersonaCreateRequest, PersonaUpdateRequest
+from synapse.communication.persona_pool import load_personas_from_file, save_personas_to_file
+from synapse.protocol import Persona
+
+router = APIRouter()
+
+
+@router.get("/sessions/{session_id}/personas")
+async def list_personas(session_id: str, request: Request):
+    container = request.app.state.runtime_container
+    try:
+        container.get_session(session_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    return load_personas_from_file()
+
+
+@router.post("/sessions/{session_id}/personas", status_code=201)
+async def create_persona(
+    session_id: str,
+    body: PersonaCreateRequest,
+    request: Request,
+):
+    container = request.app.state.runtime_container
+    try:
+        container.get_session(session_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    if not body.name.strip():
+        raise HTTPException(status_code=400, detail="Persona name is required.")
+    if body.executor_node_id is not None and not await container.executor_node_manager.node_exists(body.executor_node_id):
+        raise HTTPException(status_code=400, detail=f"Executor node '{body.executor_node_id}' not found.")
+    normalized_name = body.name.strip()
+    persona_id = _generated_persona_id(normalized_name)
+    personas = load_personas_from_file()
+    persona = Persona(
+        persona_id=persona_id,
+        name=normalized_name,
+        avatar=body.avatar,
+        base_prompt=body.base_prompt,
+        executor_node_id=body.executor_node_id,
+    )
+    updated_personas = [*personas, persona]
+    save_personas_to_file(updated_personas)
+    await container.sync_persisted_personas(updated_personas)
+    return persona
+
+
+@router.patch("/sessions/{session_id}/personas/{persona_id}")
+async def update_persona(
+    session_id: str,
+    persona_id: str,
+    body: PersonaUpdateRequest,
+    request: Request,
+):
+    container = request.app.state.runtime_container
+    try:
+        container.get_session(session_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    personas = load_personas_from_file()
+    persona = next((item for item in personas if item.persona_id == persona_id), None)
+    if persona is None:
+        raise HTTPException(status_code=404, detail=f"Persona '{persona_id}' not found.")
+    updates: dict[str, object] = {}
+    if "name" in body.model_fields_set:
+        if body.name is None or not body.name.strip():
+            raise HTTPException(status_code=400, detail="Persona name is required.")
+        updates["name"] = body.name.strip()
+    if "avatar" in body.model_fields_set:
+        if body.avatar is None:
+            raise HTTPException(status_code=400, detail="Persona avatar is required.")
+        updates["avatar"] = body.avatar
+    if "base_prompt" in body.model_fields_set:
+        if body.base_prompt is None:
+            raise HTTPException(status_code=400, detail="Persona base prompt is required.")
+        updates["base_prompt"] = body.base_prompt
+    if "executor_node_id" in body.model_fields_set:
+        if body.executor_node_id is not None and not await container.executor_node_manager.node_exists(body.executor_node_id):
+            raise HTTPException(status_code=400, detail=f"Executor node '{body.executor_node_id}' not found.")
+        updates["executor_node_id"] = body.executor_node_id
+    updated = persona.model_copy(update=updates) if updates else persona
+    if updates:
+        updated_personas = [
+            updated if item.persona_id == persona_id else item
+            for item in personas
+        ]
+        save_personas_to_file(updated_personas)
+        await container.sync_persisted_personas(updated_personas)
+    return updated
+
+
+@router.delete("/sessions/{session_id}/personas/{persona_id}")
+async def delete_persona(
+    session_id: str,
+    persona_id: str,
+    request: Request,
+):
+    container = request.app.state.runtime_container
+    try:
+        container.get_session(session_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    personas = load_personas_from_file()
+    persona = next((item for item in personas if item.persona_id == persona_id), None)
+    if persona is None:
+        raise HTTPException(status_code=404, detail=f"Persona '{persona_id}' not found.")
+    if await container.persona_is_busy(persona_id):
+        raise HTTPException(status_code=409, detail=f"Persona '{persona_id}' is busy and cannot be deleted.")
+    updated_personas = [item for item in personas if item.persona_id != persona_id]
+    save_personas_to_file(updated_personas)
+    await container.sync_persisted_personas(updated_personas)
+    return {"deleted": persona_id}
+
+
+def _generated_persona_id(name: str) -> str:
+    slug = "-".join(name.strip().lower().split())
+    return f"persona-{slug or 'bro'}-{uuid4().hex[:8]}"

synapse/api/routes/session_config.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel
+
+from synapse.communication.persona_pool import (
+    load_communication_persona_prompt_from_file,
+    save_communication_persona_prompt_to_file,
+)
+
+router = APIRouter()
+
+ALLOWED_CONFIG_KEYS = frozenset({
+    "communication_persona_prompt",
+})
+
+
+class SessionConfigValue(BaseModel):
+    value: str
+
+
+def _validate_key(key: str) -> None:
+    if key not in ALLOWED_CONFIG_KEYS:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Unknown config key '{key}'. Allowed keys: {', '.join(sorted(ALLOWED_CONFIG_KEYS))}",
+        )
+
+
+@router.get("/sessions/{session_id}/config/{key}")
+async def get_session_config(session_id: str, key: str, request: Request):
+    _validate_key(key)
+    container = request.app.state.runtime_container
+    try:
+        container.get_session(session_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    # Read from the persisted file, not the live blackboard.
+    # The blackboard value is frozen at session start.
+    if key == "communication_persona_prompt":
+        value = load_communication_persona_prompt_from_file()
+    else:
+        value = None
+    return {"key": key, "value": value}
+
+
+@router.put("/sessions/{session_id}/config/{key}")
+async def put_session_config(
+    session_id: str,
+    key: str,
+    body: SessionConfigValue,
+    request: Request,
+):
+    _validate_key(key)
+    container = request.app.state.runtime_container
+    try:
+        container.get_session(session_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    # Persist to file only. The current session's blackboard is not updated;
+    # the new value takes effect on the next session start.
+    if key == "communication_persona_prompt":
+        save_communication_persona_prompt_to_file(body.value)
+    return {"key": key, "value": body.value}