feat(hook): built-in JSONL trace exporter via Hook (issue agentscope-ai#942) (agentscope-ai#983)

## What

Implements a built-in, out-of-the-box local JSONL trace exporter for
AgentScope-Java based on the existing `Hook` event system (issue agentscope-ai#942).

This makes it easy to dump a complete “LLM conversation + execution
trace” to a local file for offline debugging / incident review /
attaching to issues, without requiring Studio or custom hook code for
every user.

## Why

When troubleshooting Agent runs, users often need a simple, local,
offline, file-based trace that includes:
- user input and final agent output
- every reasoning input/output (PreReasoning/PostReasoning)
- optional streaming chunks (ReasoningChunk / ActingChunk)
- optional tool events (PreActing/PostActing)
- basic metadata (timestamp, agent info, run/turn/step id)
- optional trace/span id if OpenTelemetry is enabled

Existing options (`JsonSession`/`Memory`/Studio) are useful but not a
direct substitute for a lightweight, portable audit log.

## Changes

- Added built-in exporter:
-
`agentscope-core/src/main/java/io/agentscope/core/hook/recorder/JsonlTraceExporter.java`
  - Writes one JSON object per hook event line (JSONL)
- Default events: `PRE_CALL`, `POST_CALL`, `PRE_REASONING`,
`POST_REASONING`, `PRE_ACTING`, `POST_ACTING`, `ERROR`
- Optional: `.includeReasoningChunks(true)`,
`.includeActingChunks(true)`, `.includeSummary(true)`,
`.includeSummaryChunks(true)`
- Best-effort by default (does not break agent execution on
IO/serialization errors), configurable `failFast(true)`
- Uses Reactor `boundedElastic` to avoid blocking agent execution
threads
- Attempts to attach `trace_id`/`span_id` via reflection when
OpenTelemetry is present (no hard dependency)

- Added tests:
-
`agentscope-core/src/test/java/io/agentscope/core/hook/recorder/JsonlTraceExporterTest.java`

- Updated example to demonstrate usage:
-
`agentscope-examples/quickstart/src/main/java/io/agentscope/examples/quickstart/HookExample.java`
  - Adds exporter hook and uses try-with-resources to ensure flush/close

- Updated docs:
  - `docs/en/task/hook.md`
  - `docs/zh/task/hook.md`

## Output Format (JSONL)

Each line contains common fields like:
- `ts`, `event_type`, `agent_id`, `agent_name`
- `run_id`, `turn_id`, `step_id`
- optional `trace_id`, `span_id`

And event-specific payloads, e.g.:
- `input_messages` (PreCall/PreReasoning/PreSummary)
- `reasoning_message` (PostReasoning)
- `final_message` (PostCall)
- `tool_use` / `tool_result` (Acting events)
- `incremental_chunk` / `accumulated` (chunk events)
- `error_class` / `error_message` / `stacktrace` (ErrorEvent)

## How To Use

```java
import io.agentscope.core.hook.recorder.JsonlTraceExporter;
import java.nio.file.Path;

try (JsonlTraceExporter exporter =
        JsonlTraceExporter.builder(Path.of("logs", "agentscope-trace.jsonl"))
                .includeReasoningChunks(true)
                .includeActingChunks(true)
                .build()) {
    ReActAgent agent = ReActAgent.builder()
            .name("Assistant")
            .model(model)
            .toolkit(toolkit)
            .hooks(List.of(exporter))
            .build();
}

Author: park338

.github/workflows/maven-ci.yml

@@ -109,8 +109,16 @@ jobs:
 
       - name: Build and Test with Coverage [Linux]
         if: runner.os == 'Linux'
+        shell: bash
         run: |
           export PATH="$HOME/.mvnd/bin:$PATH"
+          if ! command -v mvnd >/dev/null 2>&1; then
+            echo "mvnd not found, installing..."
+            curl -fsSL https://github.com/apache/maven-mvnd/releases/download/${{ env.MVND_VERSION }}/maven-mvnd-${{ env.MVND_VERSION }}-linux-amd64.tar.gz | tar xz
+            mkdir -p ~/.mvnd
+            mv maven-mvnd-${{ env.MVND_VERSION }}-linux-amd64/* ~/.mvnd/
+            export PATH="$HOME/.mvnd/bin:$PATH"
+          fi
           # -T1: single-threaded build so reactor order is respected and agentscope-core
           # is installed before modules (e.g. subagent) that resolve it from the reactor.
           mvnd -B -T1 clean verify

agentscope-core/pom.xml

@@ -140,5 +140,11 @@
             <groupId>com.networknt</groupId>
             <artifactId>json-schema-validator</artifactId>
         </dependency>
+
+        <dependency>
+            <groupId>io.opentelemetry</groupId>
+            <artifactId>opentelemetry-api</artifactId>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 </project>