fix(server): cast finished listener call, remove stale TODO, document execute contract

Author: JakubWorek

.betterer.results

@@ -4,10 +4,5 @@
 // https://phenomnomnominal.github.io/betterer/docs/results-file/#merge
 //
 exports[`TypeScript Strict Mode`] = {
-  value: `{
-    "src/server/events/execution_event_bus.ts:1102247656": [
-      [233, 15, 4, "tsc: Expected 2 arguments, but got 1.", "2087764327"],
-      [254, 15, 4, "tsc: Expected 2 arguments, but got 1.", "2087764327"]
-    ]
-  }`
+  value: `{}`
 };

src/server/agent_execution/agent_executor.ts

@@ -5,6 +5,11 @@ export interface AgentExecutor {
   /**
    * Executes the agent logic and publishes events to the bus.
    *
+   * Every call MUST publish either a `task` or a `message` event as its
+   * first event — including follow-up turns where `requestContext.task`
+   * is already set. The server enforces this ordering and rejects
+   * streams that begin with a `statusUpdate` or `artifactUpdate`.
+   *
    * Multi-tenant implementations can read the tenant identifier from
    * `requestContext.context.tenant`.
    */

src/server/events/execution_event_bus.ts

@@ -231,7 +231,7 @@ export class DefaultExecutionEventBus extends EventTarget implements ExecutionEv
 
   private addFinishedListenerInternal(listener: Listener): void {
     const wrapped: WrappedListener = () => {
-      listener.call(this);
+      (listener as () => void).call(this);
     };
 
     this.trackListener(this.finishedListeners, listener, wrapped);
@@ -252,7 +252,7 @@ export class DefaultExecutionEventBus extends EventTarget implements ExecutionEv
   private addFinishedListenerOnceInternal(listener: Listener): void {
     const wrapped: WrappedListener = () => {
       this.untrackWrappedListener(this.finishedListeners, listener, wrapped);
-      listener.call(this);
+      (listener as () => void).call(this);
     };
 
     this.trackListener(this.finishedListeners, listener, wrapped);

src/server/transports/jsonrpc/jsonrpc_transport_handler.ts

@@ -131,17 +131,13 @@ export class JsonRpcTransportHandler {
               };
             }
           } catch (streamError) {
-            // If the underlying agent stream throws an error, we need to yield a JSONRPCErrorResponse.
-            // However, an AsyncGenerator is expected to yield JSONRPCResult.
-            // This indicates an issue with how errors from the agent's stream are propagated.
-            // For now, log it. The Express layer will handle the generator ending.
+            // Re-thrown errors are caught by the Express layer, which
+            // writes a final SSE `event: error` frame carrying the
+            // JSON-RPC error envelope before closing the stream.
             console.error(
               `Error in agent event stream for ${method} (request ${requestId}):`,
               streamError
             );
-            // Ideally, the Express layer should catch this and send a final error to the client if the stream breaks.
-            // Or, the agentEventStream itself should yield a final error event that gets wrapped.
-            // For now, we re-throw so it can be caught by the Express layer streaming support.
             throw streamError;
           }
         })();