openvox-core 0.1.0__py3-none-any.whl

openvox/__init__.py

@@ -0,0 +1,3 @@
+"""OpenVox — local-first voice agent platform."""
+
+__version__ = "0.1.0"

openvox/api/__init__.py

@@ -0,0 +1,3 @@
+from openvox.api.app import create_app
+
+__all__ = ["create_app"]

openvox/api/app.py

@@ -0,0 +1,210 @@
+"""FastAPI app factory."""
+
+from __future__ import annotations
+
+import logging
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from openvox.api.routes import (
+    admin as admin_routes,
+    agents,
+    auth as auth_routes,
+    documents as documents_routes,
+    evals as evals_routes,
+    health,
+    jobs as jobs_routes,
+    mcp as mcp_routes,
+    playground,
+    pricing as pricing_routes,
+    providers as providers_routes,
+    rtc,
+    sessions,
+    skills as skills_routes,
+    storage as storage_routes,
+    telephony,
+    templates as templates_routes,
+)
+from openvox.api.ws import twilio_stream as twilio_ws
+from openvox.api.ws import voice as voice_ws
+from openvox.config import get_settings
+from openvox.db import init_db
+from openvox.providers.bootstrap import register_builtins
+from openvox.scheduler import start_scheduler, stop_scheduler
+from openvox.skills.registry import get_skill_registry
+from openvox.skills.watcher import start_watcher, stop_watcher
+
+logger = logging.getLogger(__name__)
+
+
+async def _seed_builtin_personas() -> None:
+    """Upsert the built-in synthetic personas on startup.
+
+    We upsert by id so edits to the prompt in eval/personas.py take
+    effect without manual intervention, but user-edited personas
+    (different id) are left alone.
+    """
+    from openvox.db import db_session
+    from openvox.db.models import Persona
+    from openvox.eval.personas import BUILTIN_PERSONAS
+
+    async with db_session() as s:
+        for entry in BUILTIN_PERSONAS:
+            existing = await s.get(Persona, entry["id"])
+            if existing is None:
+                p = Persona(
+                    id=entry["id"],
+                    name=entry["name"],
+                    description=entry.get("description", ""),
+                    system_prompt=entry["system_prompt"],
+                    tags=entry.get("tags", []),
+                    builtin=True,
+                )
+                s.add(p)
+            else:
+                # Refresh prompt + tags on every boot so prompt iterations stick.
+                existing.name = entry["name"]
+                existing.description = entry.get("description", "")
+                existing.system_prompt = entry["system_prompt"]
+                existing.tags = entry.get("tags", [])
+                existing.builtin = True
+
+
+@asynccontextmanager
+async def _lifespan(app: FastAPI):
+    settings = get_settings()
+    settings.data_dir.mkdir(parents=True, exist_ok=True)
+    register_builtins()
+    get_skill_registry()  # discover
+    await init_db()
+    await _seed_builtin_personas()
+    await start_scheduler()
+    await start_watcher()  # hot-reload skills dropped in ~/.openvox/skills/
+    # Phase 2: start telegram polling tasks for any agent connected
+    # in polling mode. Webhook-mode agents bootstrap themselves on the
+    # next incoming Telegram POST — no startup action needed.
+    from openvox.telephony.telegram_polling import start_all_pollers, stop_all_pollers
+    await start_all_pollers()
+    # WhatsApp Personal: reconnect bridge sessions for any agent whose
+    # channels.whatsapp_personal.enabled == true. No-op if the bridge
+    # container isn't running (opt-in via --profile whatsapp).
+    from openvox.telephony.whatsapp_personal import (
+        start_all_sessions as wpp_start_all,
+        stop_all_sessions as wpp_stop_all,
+    )
+    await wpp_start_all()
+    logger.info("OpenVox core started — auth=%s storage=%s", settings.openvox_auth, settings.storage_backend)
+    yield
+    await wpp_stop_all()
+    await stop_all_pollers()
+    await stop_watcher()
+    await stop_scheduler()
+    logger.info("OpenVox core shutting down")
+
+
+def create_app() -> FastAPI:
+    settings = get_settings()
+    logging.basicConfig(level=settings.log_level.upper())
+
+    app = FastAPI(
+        title="OpenVox Core",
+        description="Voice agent pipeline (STT + LLM + TTS + RTC + telephony).",
+        version="0.1.0",
+        lifespan=_lifespan,
+    )
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],  # local-first — accept dashboard from any local origin
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    app.include_router(health.router)
+    app.include_router(auth_routes.router, prefix="/api/v1/auth", tags=["auth"])
+    app.include_router(admin_routes.router, prefix="/api/v1/admin", tags=["admin"])
+    app.include_router(agents.router, prefix="/api/v1/agents", tags=["agents"])
+    app.include_router(documents_routes.router, prefix="/api/v1/agents", tags=["documents"])
+    app.include_router(sessions.router, prefix="/api/v1/sessions", tags=["sessions"])
+    app.include_router(providers_routes.router, prefix="/api/v1/providers", tags=["providers"])
+    app.include_router(skills_routes.router, prefix="/api/v1/skills", tags=["skills"])
+    app.include_router(templates_routes.router, prefix="/api/v1/templates", tags=["templates"])
+    app.include_router(rtc.router, prefix="/api/v1/rtc", tags=["rtc"])
+    app.include_router(jobs_routes.router, prefix="/api/v1/jobs", tags=["jobs"])
+    app.include_router(mcp_routes.router, prefix="/api/v1/mcp", tags=["mcp"])
+    app.include_router(telephony.router, prefix="/api/v1/telephony", tags=["telephony"])
+    app.include_router(pricing_routes.router, prefix="/api/v1/pricing", tags=["pricing"])
+    app.include_router(evals_routes.router, prefix="/api/v1/evals", tags=["evals"])
+    app.include_router(playground.router, prefix="/api/v1/playground", tags=["playground"])
+    app.include_router(storage_routes.router, prefix="/storage", tags=["storage"])
+    app.include_router(voice_ws.router)
+    app.include_router(twilio_ws.router)
+
+    # ── Optional static-dashboard serving ───────────────────────────
+    # Phase 1 PR-3 scaffolding: when the dashboard has been built with
+    # BUILD_OUTPUT=export (Next.js static export → `out/` directory),
+    # FastAPI serves it at /dashboard/* on the same port as the API.
+    # This is what enables the single-process CLI experience
+    # (`openvox run` → one process, browser opens to localhost:8000/dashboard).
+    #
+    # Discovery order — first existing path wins:
+    #   1. OPENVOX_DASHBOARD_PATH env var (explicit override)
+    #   2. /app/dashboard_static/    (Docker/CLI install — bundled at build)
+    #   3. ../apps/dashboard/out/    (repo-relative dev workflow)
+    #
+    # If none of the above exist, the mount is silently skipped —
+    # browsers hitting /dashboard get 404, which is correct for Docker
+    # mode (where the separate `openvox-dashboard` container handles it).
+    #
+    # Today this is no-op: the dashboard's static-export build pipeline
+    # ships in a follow-up commit (the agents/[id] route needs to be
+    # refactored to query params first — Next.js static export can't
+    # handle dynamic path params for runtime-created IDs). The mount
+    # itself is committed now so we don't have to revisit api/app.py
+    # in that follow-up — just produce the out/ directory and it
+    # gets served automatically.
+    _maybe_mount_dashboard_static(app)
+
+    return app
+
+
+def _maybe_mount_dashboard_static(app: FastAPI) -> None:
+    """Mount the built dashboard static files under /dashboard/* if available.
+
+    See the comment block in create_app() above for the discovery
+    rules + why this is a no-op today. Pulled into its own function so
+    it can be unit-tested + so the mount logic doesn't clutter the
+    main app factory.
+    """
+    import os
+    from pathlib import Path
+
+    from fastapi.staticfiles import StaticFiles
+
+    explicit = os.environ.get("OPENVOX_DASHBOARD_PATH")
+    candidates: list[Path] = []
+    if explicit:
+        candidates.append(Path(explicit))
+    candidates.append(Path("/app/dashboard_static"))
+    # Repo-relative — works in `openvox run` invoked from the repo root.
+    candidates.append(Path(__file__).resolve().parent.parent.parent.parent.parent
+                      / "apps" / "dashboard" / "out")
+
+    for path in candidates:
+        if path.is_dir() and (path / "index.html").exists():
+            app.mount(
+                "/dashboard",
+                StaticFiles(directory=str(path), html=True),
+                name="dashboard",
+            )
+            logger.info("dashboard static files mounted at /dashboard from %s", path)
+            return
+
+    # Not found — that's fine in Docker mode where the separate
+    # `openvox-dashboard` container serves the dashboard on its own port.
+    logger.debug(
+        "no dashboard static files found — /dashboard will 404. "
+        "Either set OPENVOX_DASHBOARD_PATH or use Docker dashboard service."
+    )

openvox/api/routes/admin.py

@@ -0,0 +1,133 @@
+"""Admin endpoints — backing API for the dashboard's first-run wizard.
+
+Phase 3 of `docs/PLANNING_SESSION15.md`. Three endpoints:
+
+- ``GET  /api/v1/admin/setup/status``   — what's configured + is setup complete?
+- ``POST /api/v1/admin/setup/keys``     — save provider keys (encrypted-at-rest)
+- ``DELETE /api/v1/admin/setup/keys``   — remove a stored key
+
+The dashboard's wizard pages (``apps/dashboard/src/app/dashboard/setup/*``)
+poll status on mount, present the form when ``complete == false``, and
+POST the user's pasted keys here. The encrypted-store layer
+(``openvox/secrets.py``) handles persistence; this module is just the
+HTTP shell.
+
+Security notes
+==============
+- Endpoints don't require auth today because OpenVox runs local-first;
+  the operator and the admin are the same person. When
+  ``OPENVOX_AUTH=enabled`` (multi-tenant cloud), these must be gated
+  behind admin-only authorization — see the TODO at the top of
+  ``check_admin()`` below.
+- POSTed values flow into Fernet-encrypted storage. Never logged or
+  returned in any response.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from openvox import secrets as secret_store
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+def check_admin() -> None:
+    """Authorization placeholder for the multi-tenant future.
+
+    Today: no-op. OpenVox runs local-first; operator == admin.
+
+    When ``OPENVOX_AUTH=enabled`` ships (cloud mode), this should
+    inspect the request's bearer token and 403 if the caller isn't
+    an admin. Keep all admin endpoints calling this so the eventual
+    gate has a single edit point.
+    """
+    # TODO: when OPENVOX_AUTH lands, verify admin role from JWT.
+    return None
+
+
+class SetupKeysRequest(BaseModel):
+    """Save one or more provider keys at once.
+
+    Example body:
+        {
+          "provider": "byteplus",
+          "keys": {
+            "llm_api_key": "01a2b3c4...",
+            "voice_api_key": "01a2b3c4..."
+          }
+        }
+
+    An empty string for a key value deletes the stored key (caller
+    can use this to "forget" a key without a separate DELETE call).
+    """
+
+    provider: str = Field(..., min_length=1, max_length=64)
+    keys: dict[str, str] = Field(default_factory=dict)
+
+
+@router.get("/setup/status")
+async def setup_status() -> dict[str, Any]:
+    """Tell the dashboard whether the first-run wizard should run.
+
+    Used by ``apps/dashboard/src/app/dashboard/layout.tsx`` (or
+    equivalent) on mount: if ``complete == false`` and the user
+    isn't already on /dashboard/setup, redirect them there.
+    """
+    check_admin()
+    return await secret_store.setup_complete()
+
+
+@router.post("/setup/keys")
+async def setup_keys(req: SetupKeysRequest) -> dict[str, Any]:
+    """Persist a batch of provider keys.
+
+    Returns the updated setup-status so the wizard can refresh its
+    "what's configured" panel without a second round-trip.
+    """
+    check_admin()
+
+    provider = req.provider.strip().lower()
+    if not provider:
+        raise HTTPException(400, "provider is required")
+    if not req.keys:
+        raise HTTPException(400, "keys map must be non-empty")
+
+    saved: list[str] = []
+    deleted: list[str] = []
+    for key_name, value in req.keys.items():
+        try:
+            await secret_store.set_provider_key(provider, key_name, value)
+        except ValueError as e:
+            raise HTTPException(400, f"invalid key '{key_name}': {e}") from e
+        (deleted if value == "" else saved).append(key_name)
+
+    logger.info(
+        "admin/setup/keys: provider=%s saved=%s deleted=%s",
+        provider, saved, deleted,
+    )
+
+    return {
+        "ok": True,
+        "saved": saved,
+        "deleted": deleted,
+        "status": await secret_store.setup_complete(),
+    }
+
+
+class DeleteKeyRequest(BaseModel):
+    provider: str = Field(..., min_length=1, max_length=64)
+    key_name: str = Field(..., min_length=1, max_length=64)
+
+
+@router.delete("/setup/keys")
+async def delete_key(req: DeleteKeyRequest) -> dict[str, Any]:
+    """Remove a single stored key — env-var fallback resumes."""
+    check_admin()
+    await secret_store.delete_provider_key(req.provider, req.key_name)
+    return {"ok": True, "status": await secret_store.setup_complete()}

openvox/api/routes/agents.py

@@ -0,0 +1,340 @@
+"""Agent CRUD."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+from sqlalchemy import delete, select
+
+from openvox.config import get_settings
+from openvox.db import db_session
+from openvox.db.models import (
+    Agent,
+    AgentStatus,
+    Document,
+    DocumentChunk,
+    EvalRun,
+    JobRun,
+    Recording,
+    ScheduledJob,
+    Session as DBSession,
+    Transcript,
+)
+
+router = APIRouter()
+
+
+class AgentIn(BaseModel):
+    name: str
+    description: str = ""
+    template_id: str | None = None
+    stt_provider: str = "byteplus"
+    tts_provider: str = "byteplus"
+    llm_provider: str = "byteplus"
+    # Empty → server fills from settings.byteplus_llm_model on create.
+    llm_model: str = ""
+    voice_id: str = ""
+    voice_speed: float = 1.0
+    voice_language: str = "en-US"
+    system_prompt: str = "You are a helpful voice assistant."
+    greeting: str = "Hi, how can I help you?"
+    temperature: float = 0.7
+    max_tokens: int = 2048
+    skills: list[str] = Field(default_factory=list)
+    channels: dict[str, Any] = Field(default_factory=dict)
+    mcp_servers: list[dict[str, Any]] = Field(default_factory=list)
+    voice_map: dict[str, str] = Field(default_factory=dict)
+    # "silero" (default) | "none" — controls server-side VAD interrupt path.
+    vad_provider: str = "silero"
+
+
+class AgentOut(AgentIn):
+    id: str
+    status: str
+    created_at: str
+    updated_at: str
+
+
+def _to_out(a: Agent) -> dict[str, Any]:
+    return {
+        "id": a.id,
+        "name": a.name,
+        "description": a.description,
+        "template_id": a.template_id,
+        "stt_provider": a.stt_provider,
+        "tts_provider": a.tts_provider,
+        "llm_provider": a.llm_provider,
+        "llm_model": a.llm_model,
+        "voice_id": a.voice_id,
+        "voice_speed": a.voice_speed,
+        "voice_language": a.voice_language,
+        "system_prompt": a.system_prompt,
+        "greeting": a.greeting,
+        "temperature": a.temperature,
+        "max_tokens": a.max_tokens,
+        "skills": a.skills or [],
+        "channels": a.channels or {},
+        "mcp_servers": a.mcp_servers or [],
+        "voice_map": a.voice_map or {},
+        "vad_provider": getattr(a, "vad_provider", "silero") or "silero",
+        "status": a.status,
+        "created_at": a.created_at.isoformat() if a.created_at else "",
+        "updated_at": a.updated_at.isoformat() if a.updated_at else "",
+    }
+
+
+@router.get("")
+async def list_agents() -> list[dict[str, Any]]:
+    async with db_session() as s:
+        rows = (await s.execute(select(Agent).order_by(Agent.updated_at.desc()))).scalars().all()
+        return [_to_out(a) for a in rows]
+
+
+@router.post("", status_code=201)
+async def create_agent(body: AgentIn) -> dict[str, Any]:
+    settings = get_settings()
+    fields = body.model_dump()
+    # Fill in env-driven defaults for fields the caller left blank.
+    if not fields.get("llm_model"):
+        fields["llm_model"] = settings.byteplus_llm_model
+    if not fields.get("voice_id"):
+        fields["voice_id"] = settings.byteplus_tts_default_voice
+    async with db_session() as s:
+        a = Agent(**fields)
+        s.add(a)
+        await s.flush()
+        return _to_out(a)
+
+
+@router.get("/{agent_id}")
+async def get_agent(agent_id: str) -> dict[str, Any]:
+    async with db_session() as s:
+        a = await s.get(Agent, agent_id)
+        if a is None:
+            raise HTTPException(404, "agent not found")
+        return _to_out(a)
+
+
+@router.put("/{agent_id}")
+async def update_agent(agent_id: str, body: AgentIn) -> dict[str, Any]:
+    async with db_session() as s:
+        a = await s.get(Agent, agent_id)
+        if a is None:
+            raise HTTPException(404, "agent not found")
+        for k, v in body.model_dump().items():
+            setattr(a, k, v)
+        await s.flush()
+        return _to_out(a)
+
+
+@router.post("/{agent_id}/publish")
+async def publish_agent(agent_id: str) -> dict[str, Any]:
+    async with db_session() as s:
+        a = await s.get(Agent, agent_id)
+        if a is None:
+            raise HTTPException(404, "agent not found")
+        a.status = AgentStatus.PUBLISHED.value
+        await s.flush()
+        return _to_out(a)
+
+
+@router.delete("/{agent_id}", status_code=204)
+async def delete_agent(agent_id: str) -> None:
+    """Delete an agent + every row that references it.
+
+    The agent table has two hard FK dependents (Session, Document) and
+    several soft string-keyed dependents added across later sessions
+    (DocumentChunk, ScheduledJob, JobRun, Recording, EvalRun). The
+    hard FKs cause a `ForeignKeyViolationError` if children are not
+    deleted first; the soft ones don't block delete but leave orphan
+    rows that clutter the eval framework, RAG store, and scheduler.
+
+    Pattern: cascade in dependency order, then `s.delete(a)`. Plain
+    `s.delete(a)` with `relationship(cascade="all, delete-orphan")`
+    has historically been unreliable in async-mode SQLAlchemy when
+    the relationship isn't pre-loaded — see bugs #29, #30 in
+    CLAUDE.md §8. In-route cascades are slower but bulletproof.
+    """
+    async with db_session() as s:
+        a = await s.get(Agent, agent_id)
+        if a is None:
+            raise HTTPException(404, "agent not found")
+
+        # 1. Eval framework — runs reference the agent directly,
+        #    recordings via source_agent_id.
+        await s.execute(delete(EvalRun).where(EvalRun.agent_id == agent_id))
+        await s.execute(delete(Recording).where(Recording.source_agent_id == agent_id))
+
+        # 2. Scheduler — kill job_runs first (FK to scheduled_jobs),
+        #    then the jobs themselves. Same pattern as the
+        #    /api/v1/jobs/{id} route uses (CLAUDE.md §8 #29).
+        job_ids = (
+            await s.execute(select(ScheduledJob.id).where(ScheduledJob.agent_id == agent_id))
+        ).scalars().all()
+        if job_ids:
+            await s.execute(delete(JobRun).where(JobRun.job_id.in_(job_ids)))
+        await s.execute(delete(ScheduledJob).where(ScheduledJob.agent_id == agent_id))
+
+        # 3. Voice / text sessions — transcripts FK to sessions, so
+        #    clear those first. Hard FK constraint.
+        session_ids = (
+            await s.execute(select(DBSession.id).where(DBSession.agent_id == agent_id))
+        ).scalars().all()
+        if session_ids:
+            await s.execute(delete(Transcript).where(Transcript.session_id.in_(session_ids)))
+        await s.execute(delete(DBSession).where(DBSession.agent_id == agent_id))
+
+        # 4. Documents + RAG chunks. Hard FK on Document, soft on chunks.
+        await s.execute(delete(DocumentChunk).where(DocumentChunk.agent_id == agent_id))
+        await s.execute(delete(Document).where(Document.agent_id == agent_id))
+
+        # 5. Finally the agent itself.
+        await s.delete(a)
+
+
+# ── Session 10: text-mode turn for the Setup Assistant ───────────────
+# The Setup Assistant ships as a voice agent but the user-facing
+# component supports both voice AND typed input. Voice goes through the
+# existing /ws/voice WS; text comes in here. Both invoke the same agent
+# + skills, both write to the same Agent.channels.setup_state, so the
+# "draft" state stays consistent when the user switches mid-flow.
+#
+# Out of scope for v1: streaming. The skill-loop nature of an LLM round
+# (LLM → maybe-tool-call → result → re-invoke LLM) is awkward to stream
+# over a single HTTP response; the SetupAssistant doesn't need it
+# because typed input is naturally turn-based. Reply payload includes
+# every event the orchestrator would have emitted, in order.
+
+
+class TurnRequest(BaseModel):
+    user_text: str
+    # Optional — lets the caller carry a conversational history across
+    # turns. Each item is `{"role": "user"|"assistant", "content": "..."}`.
+    # If omitted we treat this as a fresh turn (still uses the agent's
+    # configured system_prompt + greeting).
+    history: list[dict[str, Any]] = Field(default_factory=list)
+
+
+@router.post("/{agent_id}/turn")
+async def agent_text_turn(agent_id: str, body: TurnRequest) -> dict[str, Any]:
+    """Run a single LLM turn (with skill calls) against `agent_id`.
+
+    Returns the assistant text plus an array of every event the
+    orchestrator emitted (skill_call / skill_result / errors) so the
+    SetupAssistant UI can render a faithful transcript even when the
+    LLM took a multi-step tool path.
+    """
+    import json
+
+    from openvox.providers import ProviderType, get_registry
+    from openvox.providers.base import LLMConfig, LLMMessage, LLMProvider
+    from openvox.skills import SkillContext
+    from openvox.skills.runner import SkillRunner
+
+    user_text = (body.user_text or "").strip()
+    if not user_text:
+        raise HTTPException(400, "user_text is required")
+
+    async with db_session() as s:
+        a = await s.get(Agent, agent_id)
+        if a is None:
+            raise HTTPException(404, "agent not found")
+        system_prompt = a.system_prompt
+        skill_ids = list(a.skills or [])
+        llm_id = a.llm_provider
+        llm_model = a.llm_model
+        temperature = a.temperature
+        max_tokens = a.max_tokens
+
+    llm = get_registry().get(ProviderType.LLM, llm_id)
+    if not isinstance(llm, LLMProvider) or not llm.is_available():
+        raise HTTPException(400, f"LLM provider '{llm_id}' unavailable")
+
+    runner = SkillRunner(
+        skill_ids=skill_ids,
+        ctx=SkillContext(agent_id=agent_id, metadata={"source": "agent_text_turn"}),
+    )
+
+    # Build a fresh message list — system prompt + caller-supplied
+    # history + the new user turn. We're not persisting history here;
+    # the SetupAssistant client carries it. Keeps this endpoint stateless
+    # at the HTTP layer while still letting the LLM see the full thread.
+    messages: list[LLMMessage] = [LLMMessage(role="system", content=system_prompt)]
+    for h in body.history:
+        role = h.get("role")
+        content = h.get("content") or ""
+        if role in {"user", "assistant"} and content:
+            messages.append(LLMMessage(role=role, content=content))
+    messages.append(LLMMessage(role="user", content=user_text))
+
+    cfg = LLMConfig(
+        model=llm_model,
+        temperature=temperature,
+        max_tokens=max_tokens,
+        stream=False,
+        tools=runner.tool_specs() or None,
+    )
+
+    # ── Skill loop ───────────────────────────────────────────────────
+    # Mirrors `orchestrator._llm_turn`'s shape but in non-streaming mode
+    # because text replies don't need sub-sentence chunking. Same cap
+    # on tool iterations (default 6) for the same reason —
+    # see CLAUDE.md §8 #46.
+    events: list[dict[str, Any]] = []
+    full_text = ""
+    max_iters = 6
+
+    for iteration in range(max_iters):
+        # Non-streaming call returns one chunk with the full delta
+        # plus possibly tool_calls.
+        last_chunk = None
+        async for chunk in llm.chat_stream(messages, cfg):
+            last_chunk = chunk
+        if last_chunk is None:
+            break
+        delta = last_chunk.delta or ""
+        full_text += delta
+        if delta:
+            events.append({"type": "assistant_token", "text": delta})
+
+        tool_calls = last_chunk.tool_calls or []
+        if not tool_calls:
+            # LLM is done.
+            break
+
+        # Echo the assistant message that issued the tool_calls so the
+        # next LLM call's history is well-formed (OpenAI / Ark contract).
+        messages.append(
+            LLMMessage(role="assistant", content=delta, tool_calls=tool_calls)
+        )
+        for tc in tool_calls:
+            fn = tc.get("function") or {}
+            name = fn.get("name") or ""
+            raw_args = fn.get("arguments") or "{}"
+            try:
+                parsed_args = json.loads(raw_args) if isinstance(raw_args, str) else raw_args
+            except json.JSONDecodeError:
+                parsed_args = {"_raw": raw_args}
+            if not isinstance(parsed_args, dict):
+                parsed_args = {"_value": parsed_args}
+            events.append({"type": "skill_call", "name": name, "args": parsed_args})
+            result = await runner.invoke(name, parsed_args)
+            events.append({"type": "skill_result", "name": name, "output": result})
+            messages.append(
+                LLMMessage(
+                    role="tool",
+                    tool_call_id=tc.get("id") or "",
+                    name=name,
+                    content=json.dumps(result, ensure_ascii=False),
+                )
+            )
+    else:
+        events.append({
+            "type": "error",
+            "text": f"tool-call loop exceeded {max_iters} iterations",
+        })
+
+    events.append({"type": "assistant_done", "text": full_text})
+    return {"text": full_text, "events": events}