pipecat-ai
diff --git a/‎CHANGELOG.md‎
Lines changed: 5 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎docs/byoa-example.py‎
Lines changed: 23 additions & 1 deletion b/‎docs/byoa-example.py‎
Lines changed: 23 additions & 1 deletion
diff --git a/‎docs/byoa-vercel.md‎
Lines changed: 2 additions & 0 deletions b/‎docs/byoa-vercel.md‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎docs/byoa.md‎
Lines changed: 21 additions & 0 deletions b/‎docs/byoa.md‎
Lines changed: 21 additions & 0 deletions
diff --git a/‎src/gradientbang/runtime/bus.py‎
Lines changed: 14 additions & 0 deletions b/‎src/gradientbang/runtime/bus.py‎
Lines changed: 14 additions & 0 deletions
diff --git a/‎src/gradientbang/runtime/byoa/__init__.py‎
Lines changed: 9 additions & 2 deletions b/‎src/gradientbang/runtime/byoa/__init__.py‎
Lines changed: 9 additions & 2 deletions
diff --git a/‎src/gradientbang/runtime/byoa/app.py‎
Lines changed: 57 additions & 3 deletions b/‎src/gradientbang/runtime/byoa/app.py‎
Lines changed: 57 additions & 3 deletions
diff --git a/‎src/gradientbang/runtime/orchestrator.py‎
Lines changed: 79 additions & 9 deletions b/‎src/gradientbang/runtime/orchestrator.py‎
Lines changed: 79 additions & 9 deletions
@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Corp-ship combat now preempts normal task work by waking active TaskAgents into a combat goal or starting an idle ship task through the normal task path, while preserving the existing combat prompt and doctrine injection flow.
+- BYOA harnesses can now customize active combat wake behavior with an `@app.on_combat_wake` hook.
+
 ### Fixed
 
 - `TaskAgent._inject_steering` now injects steer text as a single `<event name="task.steered">` user message with a short priority line followed by the raw steer text inline. Same event-xml shape as `task.progress` / `task.cancelled` the agent already reads — without it, the steer was just another peer instruction to the original task description (which is itself a plain user message). Orchestrator side drops its now-redundant `"Steering instruction: "` text prefix.
 
@@ -12,7 +12,7 @@
 
 from loguru import logger
 
-from gradientbang.runtime.byoa import ByoaApp, ByoaContext
+from gradientbang.runtime.byoa import ByoaApp, ByoaCombatWake, ByoaContext
 
 
 app = ByoaApp()
@@ -61,6 +61,28 @@ def on_session_end(ctx: ByoaContext) -> None:
     )
 
 
+@app.on_combat_wake
+def on_combat_wake(ctx: ByoaContext, wake: ByoaCombatWake) -> ByoaCombatWake | None:
+    """Optionally replace the combat wake before the task context resets."""
+
+    logger.info(
+        "custom_byoa.combat_wake ship_id={} task_id={}",
+        ctx.ship_id,
+        ctx.task_id,
+    )
+
+    # Return None to use the default combat goal. Return a replacement wake
+    # when your agent should bias combat differently from the bundled prompt.
+    return ByoaCombatWake(
+        goal=(
+            f"{wake.goal}\n\n"
+            "Operator combat preference: preserve the ship first; flee if the "
+            "opponent looks stronger, otherwise brace or attack conservatively."
+        ),
+        context=wake.context,
+    )
+
+
 # Optional: override model construction.
 #
 # Leave this commented to use TASK_LLM_PROVIDER, TASK_LLM_MODEL,
 
@@ -120,6 +120,8 @@ Optional:
 - [prompt.md](../deployment/vercel/prompt.md): optional prompt starting point.
 
 Most operators only edit `.env.byoa` and optionally `prompt.md`.
+Combat wake customization lives in the Python harness, so use a fork with
+[docs/byoa-example.py](byoa-example.py) when prompt-only behavior is not enough.
 
 ## Redeploys
 
 
@@ -91,6 +91,27 @@ If attacked, flee unless the enemy is already badly damaged.
 Avoid spending fuel unless the route improves expected profit.
 ```
 
+## Combat Wake
+
+When a claimed corp ship enters combat, the bot wakes the BYOA task into a combat goal before normal event broadcast. Active agents reset their task context; idle agents start through the normal task path. The bundled combat.md and ship doctrine still load from `combat.round_waiting`, so do not duplicate them in your prompt.
+
+Use `@app.on_combat_wake` only when you need custom combat bias:
+
+```python
+from gradientbang.runtime.byoa import ByoaApp, ByoaCombatWake, ByoaContext
+
+app = ByoaApp()
+
+@app.on_combat_wake
+def combat_policy(ctx: ByoaContext, wake: ByoaCombatWake) -> ByoaCombatWake | None:
+    return ByoaCombatWake(
+        goal=f"{wake.goal}\n\nOperator preference: flee unless clearly favored.",
+        context=wake.context,
+    )
+```
+
+Return `None` to observe/log the wake without changing the default combat goal.
+
 ## Vercel
 
 Production BYOA runs through the Vercel wake receiver in [deployment/vercel](../deployment/vercel/).
 
@@ -123,6 +123,20 @@ class BusSteerTaskMessage(BusDataMessage):
     text: str = ""
 
 
+@dataclass
+class BusCombatWakeMessage(BusDataMessage):
+    """Urgent combat reprioritization for a running task agent.
+
+    The task id stays the same; the worker drops its current LLM context and
+    treats ``goal`` as the new task instruction. Combat.md and doctrine still
+    load from the next matching ``combat.round_waiting`` event.
+    """
+
+    task_id: str = ""
+    goal: str = ""
+    context: str = ""
+
+
 # ---------------------------------------------------------------------------
 # Typed game RPCs over the bus
 # ---------------------------------------------------------------------------
 
@@ -8,20 +8,27 @@
 
 * :class:`ByoaApp` — the default harness; instantiate and call ``.run()``
   for the zero-config path, or attach hooks via ``@app.prompt``, ``@app.llm``,
-  ``@app.on_session_start``, ``@app.on_session_end``.
+  ``@app.on_session_start``, ``@app.on_session_end``, ``@app.on_combat_wake``.
 * :class:`ByoaContext` — what hooks receive: ship_id, character_id, channel,
   bus_dsn, prompt, config, …
+* :class:`ByoaCombatWake` — replacement text returned from combat wake hooks.
 * :class:`ByoaAgentConfig` — runtime tunables (RPC timeouts, wake timeout,
   in-process corp-agent idle teardown).
 * :class:`ByoaConfigError` — raised for missing/malformed BYOA env vars.
 """
 
-from gradientbang.runtime.byoa.app import ByoaApp, ByoaConfigError, ByoaContext
+from gradientbang.runtime.byoa.app import (
+    ByoaApp,
+    ByoaCombatWake,
+    ByoaConfigError,
+    ByoaContext,
+)
 from gradientbang.runtime.byoa.config import ByoaAgentConfig
 
 __all__ = [
     "ByoaAgentConfig",
     "ByoaApp",
+    "ByoaCombatWake",
     "ByoaConfigError",
     "ByoaContext",
 ]
@@ -17,8 +17,9 @@
   run the bundled harness unchanged.
 * **Mode B** — instantiate :class:`ByoaApp` in your own ``module:main``,
   attach lifecycle hooks via ``@app.prompt`` / ``@app.llm`` /
-  ``@app.on_session_start`` / ``@app.on_session_end``, rebind the ``byoa``
-  console script in your fork's ``pyproject.byoa.toml`` to point at it.
+  ``@app.on_session_start`` / ``@app.on_session_end`` /
+  ``@app.on_combat_wake``, rebind the ``byoa`` console script in your
+  fork's ``pyproject.byoa.toml`` to point at it.
 """
 
 from __future__ import annotations
@@ -79,6 +80,14 @@ def from_env(cls) -> "ByoaContext":
         )
 
 
+@dataclass(frozen=True)
+class ByoaCombatWake:
+    """Combat wake instruction before the TaskAgent resets into combat."""
+
+    goal: str
+    context: str = ""
+
+
 def _require(env_key: str) -> str:
     value = (os.environ.get(env_key) or "").strip()
     if not value:
@@ -124,6 +133,7 @@ def _load_prompt() -> Optional[str]:
 PromptHook = Callable[[ByoaContext], HookResult[Optional[str]]]
 LLMHook = Callable[[ByoaContext], HookResult[Any]]
 LifecycleHook = Callable[[ByoaContext], HookResult[None]]
+CombatWakeHook = Callable[[ByoaContext, ByoaCombatWake], HookResult[Optional[ByoaCombatWake]]]
 
 
 class ByoaApp:
@@ -153,6 +163,7 @@ def __init__(self) -> None:
         self._llm_hook: Optional[LLMHook] = None
         self._on_session_start: Optional[LifecycleHook] = None
         self._on_session_end: Optional[LifecycleHook] = None
+        self._on_combat_wake: Optional[CombatWakeHook] = None
 
     # ── Decorators ────────────────────────────────────────────────────
 
@@ -187,6 +198,15 @@ def on_session_end(self, fn: LifecycleHook) -> LifecycleHook:
         self._on_session_end = fn
         return fn
 
+    def on_combat_wake(self, fn: CombatWakeHook) -> CombatWakeHook:
+        """Run before an active task is reset into combat.
+
+        Return ``None`` to keep the default combat wake, or return a
+        :class:`ByoaCombatWake` with replacement goal/context text.
+        """
+        self._on_combat_wake = fn
+        return fn
+
     # ── Entry points ──────────────────────────────────────────────────
 
     def run(self) -> None:
@@ -235,10 +255,20 @@ async def run_async(self) -> None:
             bus=bus,
             handle_sigint=True,
         )
+
+        app = self
+
+        class ByoaTaskAgent(TaskAgent):
+            """TaskAgent with BYOA harness hooks wired in."""
+
+            async def _wake_for_combat(self, goal: str, context: str = "") -> None:
+                wake = await app._apply_combat_wake(ctx, goal, context)
+                await super()._wake_for_combat(wake.goal, wake.context)
+
         # TaskAgent's character_id is the SHIP's pseudo-character (the
         # subject of every game tool call). Authorization is the bus channel
         # (capability) + corp membership + ship_byoa_configure ownership.
-        agent = TaskAgent(
+        agent = ByoaTaskAgent(
             agent_name,
             character_id=ctx.ship_id,
             is_corp_ship=True,
@@ -272,6 +302,28 @@ async def run_async(self) -> None:
             except Exception:
                 logger.exception("byoa.app.bus.stop_failed")
 
+    async def _apply_combat_wake(
+        self, ctx: ByoaContext, goal: str, context: str
+    ) -> ByoaCombatWake:
+        """Apply the optional operator combat hook; fallback is original wake."""
+        wake = ByoaCombatWake(goal=goal, context=context)
+        if self._on_combat_wake is None:
+            return wake
+        try:
+            replacement = await _maybe_await(self._on_combat_wake, ctx, wake)
+        except Exception:
+            logger.exception("byoa.app.on_combat_wake.failed")
+            return wake
+        if replacement is None:
+            return wake
+        if isinstance(replacement, ByoaCombatWake):
+            return replacement
+        logger.warning(
+            "byoa.app.on_combat_wake.ignored invalid_return_type={}",
+            type(replacement).__name__,
+        )
+        return wake
+
 
 async def _maybe_await(fn: Callable[..., HookResult[T]], *args: Any) -> T:
     """Invoke a hook that may be sync or async; await the latter."""
@@ -306,6 +358,8 @@ def _hooks_summary(app: "ByoaApp") -> str:
         names.append("on_session_start")
     if app._on_session_end is not None:
         names.append("on_session_end")
+    if app._on_combat_wake is not None:
+        names.append("on_combat_wake")
     return " ".join(names) if names else "(none)"
 
 
 
@@ -14,6 +14,7 @@
 from collections import deque
 from dataclasses import dataclass, replace
 from functools import wraps
+from types import SimpleNamespace
 from typing import Any, Callable, Dict, Optional, Tuple
 
 from loguru import logger
@@ -65,6 +66,7 @@
     BusByoaPresenceMessage,
     BusCombatStrategyRequest,
     BusCombatStrategyResponse,
+    BusCombatWakeMessage,
     BusCorporationQueryRequest,
     BusCorporationQueryResponse,
     BusGameEventMessage,
@@ -93,6 +95,11 @@
     summarize_leaderboard,
     summarize_ship_definitions,
 )
+from gradientbang.utils.combat import (
+    build_combat_task_description,
+    is_combat_participant,
+    owned_corp_ship_participant_ids,
+)
 from gradientbang.utils.summary_formatters import list_known_ports_summary
 from gradientbang.utils.prompt_loader import (
     AVAILABLE_TOPICS,
@@ -1743,16 +1750,24 @@ async def broadcast_game_event(
         self, event: Dict[str, Any], *, voice_agent_originated: bool = False
     ) -> None:
         """Broadcast a game event to the bus for TaskAgent children."""
+        event_name = event.get("event_name")
+
+        # Corp combat outranks the current task. Send the wake before the
+        # event broadcast; idle ships take the normal start_task path and act
+        # on the next live combat event.
+        if event_name == "combat.round_waiting":
+            payload = event.get("payload")
+            if isinstance(payload, dict):
+                await self._wake_corp_ship_tasks_for_combat(payload)
+
         await self.send_bus_message(
             BusGameEventMessage(
                 source=self.name, event=event, voice_agent_originated=voice_agent_originated
             )
         )
 
-        event_name = event.get("event_name")
-
         # Cancel player ship tasks when the player enters combat.
-        # Corp ship tasks continue running — they're independent.
+        # Corp ships were handled above by waking/starting combat work.
         if event_name == "combat.round_waiting":
             payload = event.get("payload")
             if isinstance(payload, dict) and self._is_player_combat_participant(payload):
@@ -1768,12 +1783,67 @@ async def broadcast_game_event(
 
     def _is_player_combat_participant(self, payload: dict) -> bool:
         """Check if our character is listed in the combat participants."""
-        participants = payload.get("participants")
-        if isinstance(participants, list):
-            for p in participants:
-                if isinstance(p, dict) and p.get("id") == self._character_id:
-                    return True
-        return False
+        return is_combat_participant(payload, self._character_id)
+
+    async def _wake_corp_ship_tasks_for_combat(self, payload: dict) -> None:
+        """Wake or start owned corp ships that are participants in round one."""
+        if payload.get("round") not in (1, "1"):
+            return
+        for ship_character_id in owned_corp_ship_participant_ids(
+            payload, self._game_client.corporation_id
+        ):
+            await self._wake_or_start_corp_ship_combat_task(ship_character_id, payload)
+
+    async def _wake_or_start_corp_ship_combat_task(
+        self, ship_character_id: str, payload: dict
+    ) -> None:
+        goal = build_combat_task_description(payload, ship_character_id)
+        combat_id = payload.get("combat_id") or payload.get("encounter_id") or "unknown"
+        context = (
+            "Combat response task. Existing combat prompt and ship doctrine will be "
+            "loaded when a combat.round_waiting event is processed.\n"
+            f"combat_id: {combat_id}"
+        )
+
+        if ship_character_id in self._locked_ships:
+            target = self._find_steer_target_by_ship(ship_character_id)
+            if target is None:
+                logger.debug(
+                    "combat_wake.locked_without_target ship={}",
+                    ship_character_id[:8],
+                )
+                return
+            await self.send_bus_message(
+                BusCombatWakeMessage(
+                    source=self.name,
+                    target=target.agent_name,
+                    task_id=target.framework_task_id,
+                    goal=goal,
+                    context=context,
+                )
+            )
+            await self._task_output_handler(
+                goal,
+                message_type="COMBAT",
+                task_id=target.framework_task_id,
+                task_type=target.task_type,
+            )
+            return
+
+        params = SimpleNamespace(
+            arguments={
+                "task_description": goal,
+                "context": context,
+                "ship_id": ship_character_id,
+            }
+        )
+        result = await self._handle_start_task(params)  # type: ignore[arg-type]
+        if not result.get("success"):
+            logger.warning(
+                "combat_wake.start_failed ship={} error={}",
+                ship_character_id[:8],
+                result.get("error") or result,
+            )
 
     async def _cancel_player_tasks_for_combat(self) -> None:
         """Cancel all active player ship tasks (not corp ship tasks)."""