feat: add --json-events mode to specsmith run, remove serve stub

- Remove dead \specsmith serve\ stub command (was placeholder for issue #14)
- Add --json-events flag to \specsmith run\: emits JSONL events over stdout
  for IDE clients (VS Code extension bridge)
- Event types: ready, llm_chunk, tool_started, tool_finished, tokens,
  turn_done, error, system
- In json_events mode: stdin is used for user messages, stdout is pure JSON,
  streaming disabled, prompt string suppressed
- AgentRunner gains json_events param and _emit_event() method

Co-Authored-By: Oz <oz-agent@warp.dev>

Author: tbitcs

src/specsmith/agent/runner.py

@@ -184,13 +184,15 @@ def __init__(
         max_tool_iterations: int = 10,
         optimize: bool = False,
         optimization_config: OptimizationConfig | None = None,
+        json_events: bool = False,
     ) -> None:
         self.project_dir = str(Path(project_dir).resolve())
         self._provider_name = provider_name
         self._model = model
         self._tier = tier
         self._stream = stream
         self._max_iterations = max_tool_iterations
+        self._json_events = json_events
 
         self._provider: Any = None
         self._state = SessionState(project_dir=self.project_dir)
@@ -291,14 +293,26 @@ def _agent_turn(self, user_input: str, silent: bool = False) -> str:
             except Exception as e:  # noqa: BLE001
                 error_msg = f"[Provider error] {e}"
                 if not silent:
-                    self._print(error_msg)
+                    if self._json_events:
+                        self._emit_event(type="error", message=error_msg)
+                    else:
+                        self._print(error_msg)
                 return error_msg
 
             # Update credit tracking
             self._state.total_input_tokens += response.input_tokens
             self._state.total_output_tokens += response.output_tokens
             self._state.total_cost_usd += response.estimated_cost_usd
 
+            # Emit token update event
+            if self._json_events and not silent:
+                self._emit_event(
+                    type="tokens",
+                    in_tokens=self._state.total_input_tokens,
+                    out_tokens=self._state.total_output_tokens,
+                    cost_usd=self._state.total_cost_usd,
+                )
+
             if response.content:
                 final_response = response.content
 
@@ -330,6 +344,14 @@ def _agent_turn(self, user_input: str, silent: bool = False) -> str:
                     )
                 )
 
+        # Emit turn-done event
+        if self._json_events and not silent:
+            self._emit_event(
+                type="turn_done",
+                total_tokens=self._state.session_tokens,
+                cost_usd=self._state.total_cost_usd,
+            )
+
         return final_response
 
     def _call_provider(self, messages: list[Message], silent: bool = False) -> CompletionResponse:
@@ -362,7 +384,7 @@ def _call_provider(self, messages: list[Message], silent: bool = False) -> Compl
             messages = hint.messages
             tools = hint.tools
 
-        use_stream = self._stream and not silent and not tools
+        use_stream = self._stream and not silent and not tools and not self._json_events
         if use_stream:
             accumulated = ""
             for token in provider.stream(messages, tools=None):
@@ -375,7 +397,10 @@ def _call_provider(self, messages: list[Message], silent: bool = False) -> Compl
         else:
             response = cast(CompletionResponse, provider.complete(messages, tools=tools))
             if not silent and response.content:
-                self._print(response.content)
+                if self._json_events:
+                    self._emit_event(type="llm_chunk", text=response.content)
+                else:
+                    self._print(response.content)
 
         # ── Optimization post-call ───────────────────────────────────────────
         if self._optimizer is not None and hint is not None:
@@ -405,7 +430,10 @@ def _execute_tool_calls(
             inputs = tc.get("input", {})
 
             if not silent:
-                self._print(f"\n[Tool: {name}]")
+                if self._json_events:
+                    self._emit_event(type="tool_started", name=name, args=inputs)
+                else:
+                    self._print(f"\n[Tool: {name}]")
 
             # Fire pre_tool hooks
             pre_ctx = HookContext(
@@ -451,9 +479,12 @@ def _execute_tool_calls(
             elapsed = time.time() * 1000 - start_ms
 
             if not silent:
-                # Truncate long outputs for display
-                display = output[:500] + "..." if len(output) > 500 else output
-                self._print(f"  → {display}")
+                if self._json_events:
+                    self._emit_event(type="tool_finished", name=name, result=output, is_error=error)
+                else:
+                    # Truncate long outputs for display
+                    display = output[:500] + "..." if len(output) > 500 else output
+                    self._print(f"  → {display}")
 
             tr = ToolResult(
                 tool_name=name,
@@ -554,13 +585,23 @@ def _on_session_end(self) -> None:
     def _print_banner(self) -> None:
         provider = getattr(self._provider, "provider_name", "?")
         model = getattr(self._provider, "model", "?")
-        self._print(
-            f"\n[specsmith agent — AEE-integrated]"
-            f"\n  Project: {self.project_dir}"
-            f"\n  Provider: {provider}/{model}"
-            f"\n  Tools: {len(self._tools)} | Skills: {len(self._skills)}"
-            f"\n  Type /help for commands, exit to quit\n"
-        )
+        if self._json_events:
+            self._emit_event(
+                type="ready",
+                provider=provider,
+                model=model,
+                project_dir=self.project_dir,
+                tools=len(self._tools),
+                skills=len(self._skills),
+            )
+        else:
+            self._print(
+                f"\n[specsmith agent — AEE-integrated]"
+                f"\n  Project: {self.project_dir}"
+                f"\n  Provider: {provider}/{model}"
+                f"\n  Tools: {len(self._tools)} | Skills: {len(self._skills)}"
+                f"\n  Type /help for commands, exit to quit\n"
+            )
 
     def _print_status(self) -> None:
         self._print(
@@ -594,10 +635,22 @@ def _print_help(self) -> None:
     def _prompt(self) -> str:
         """Read a line of input from stdin."""
         try:
-            return input("\n> ")
+            # In json_events mode suppress the prompt string so stdout stays pure JSON
+            return input("" if self._json_events else "\n> ")
         except EOFError:
             raise
 
     def _print(self, text: str = "", end: str = "\n", flush: bool = False) -> None:
-        """Print to stdout."""
-        print(text, end=end, flush=flush)
+        """Print to stdout; in json_events mode emit a system event instead."""
+        if self._json_events:
+            if text.strip():
+                self._emit_event(type="system", message=text.strip())
+        else:
+            print(text, end=end, flush=flush)
+
+    def _emit_event(self, **kwargs: Any) -> None:
+        """Emit a newline-delimited JSON event to stdout (json_events mode only)."""
+        import json
+        import sys
+
+        print(json.dumps(kwargs), flush=True, file=sys.stdout)  # noqa: T201

src/specsmith/cli.py

@@ -1809,29 +1809,6 @@ def plugin_list() -> None:
     console.print(f"\n  {len(plugins)} plugin(s)")
 
 
-# ---------------------------------------------------------------------------
-# Serve (API for React dashboard)
-# ---------------------------------------------------------------------------
-
-
-@main.command()
-@click.option("--port", default=8910, help="Port to serve on.")
-def serve(port: int) -> None:
-    """Start local API server for the web dashboard."""
-    console.print(f"[bold]Starting specsmith API server on port {port}...[/bold]")
-    console.print("[yellow]Not yet implemented. See issue #14.[/yellow]")
-    console.print(
-        "\nPlanned endpoints:\n"
-        "  GET  /api/projects          \u2014 list governed projects\n"
-        "  POST /api/projects/init     \u2014 scaffold new project\n"
-        "  POST /api/projects/import   \u2014 import existing project\n"
-        "  GET  /api/projects/:id/audit   \u2014 run audit\n"
-        "  GET  /api/projects/:id/export  \u2014 generate report\n"
-        "  GET  /api/types             \u2014 list all 30 project types\n"
-        "  GET  /api/tools/:type       \u2014 tool registry for a type"
-    )
-
-
 # ---------------------------------------------------------------------------
 # Process execution and abort
 # ---------------------------------------------------------------------------
@@ -1955,6 +1932,13 @@ def abort_cmd(pid: int | None, abort_all_flag: bool, project_dir: str) -> None:
     default=False,
     help="Enable token optimization (caching, routing, context trim, tool filtering).",
 )
+@click.option(
+    "--json-events",
+    "json_events",
+    is_flag=True,
+    default=False,
+    help="Emit structured JSONL events to stdout (used by IDE clients like the VS Code extension).",
+)
 def run_cmd(
     project_dir: str,
     task: str,
@@ -1963,6 +1947,7 @@ def run_cmd(
     tier: str,
     no_stream: bool,
     optimize: bool,
+    json_events: bool,
 ) -> None:
     """Start the AEE-integrated agentic client REPL.
 
@@ -1994,6 +1979,7 @@ def run_cmd(
             tier=tier_map[tier],
             stream=not no_stream,
             optimize=optimize,
+            json_events=json_events,
         )
         if task:
             result = runner.run_task(task)