Merge pull request #2 from CarlJi/feat/enhance_basic_test

feat: Simplify API surface and improve claude streaming correctness

Author: xushiwei

README.md

@@ -195,45 +195,29 @@ agent := opencode.New(
 
 ```go
 type Executor interface {
-	Run(ctx context.Context, req ExecRequest) (*ExecResult, error)
+	// Exec starts a command and returns a Process handle for streaming I/O.
+	// args[0] is the binary name; args[1:] are arguments.
+	Exec(ctx context.Context, args []string, env map[string]string, workDir string) (*Process, error)
 	IsHealthy(ctx context.Context) bool
 	Close(ctx context.Context) error
 }
-```
-
-### LocalExecutor
-
-`xagent.NewLocalExecutor()` — the default executor. Runs CLI binaries as child processes using `os/exec`. Zero external dependencies.
-
-### DockerExecutor (Demo)
 
-`demo/docker_xgopilot/docker` — demo-only executor implementation that runs each CLI invocation via `docker exec` inside a long-lived container. Container lifecycle (start, stop, remove) is managed automatically.
-
-```go
-import "github.com/goplus/xagent/demo/docker_xgopilot/docker"
-
-exec, err := docker.New(
-	docker.WithImage("goplusorg/codeagent:v0.9.6.1"),
-	docker.WithContainerName("my-agent"),
-	docker.WithUser("codeagent"),
-	docker.WithWorkDir("/workspace"),
-	docker.WithMounts([]docker.Mount{
-		{Host: "/host/project", Container: "/workspace"},
-	}),
-	docker.WithPathRemap(map[string]string{"/host/project": "/workspace"}),
-	docker.WithInit(true),
-	docker.WithAutoRemove(true),
-	docker.WithLogger(slog.Default()),
-)
+// Process is the handle returned by Executor.Exec.
+type Process struct {
+	Stdout io.ReadCloser                    // subprocess stdout (NDJSON/SSE stream)
+	Stdin  io.WriteCloser                   // subprocess stdin; nil when not writable
+	Wait   func() (exitCode int, err error) // blocks until process exits
+	Stderr *bytes.Buffer                    // captured stderr; read after Wait() returns
+}
 ```
 
-No external Go dependencies — requires only the `docker` CLI on `PATH`.
+### LocalExecutor
 
-**Multi-turn with DockerExecutor:** each `docker exec` call runs in a fresh subprocess, so process-level state is not retained between invocations. Claude session continuity relies on passing `--resume <session-id>` whenever a session ID is available. This behavior is not executor-conditional, and stdin is closed after each invocation for both `LocalExecutor` and `DockerExecutor`.
+`xagent.NewLocalExecutor()` — the built-in default executor. Runs CLI binaries as child processes using `os/exec`. Zero external dependencies.
 
-### E2BExecutor
+### Custom Executors
 
-`github.com/goplus/xagent/executor/e2b` — runs commands inside [E2B](https://e2b.dev) cloud sandboxes. Ships as a separate Go module with its own `go.mod`.
+Any type implementing the `Executor` interface can be used to run agent CLI binaries in a custom environment — for example, inside a Docker container, a cloud sandbox, or over SSH. Pass your implementation via the `WithExecutor()` option when constructing an adapter. See `demo/executor_docker` for a Docker-based reference implementation.
 
 ## SessionManager
 
@@ -272,16 +256,16 @@ type Event interface {
 }
 ```
 
-| Event type          | Kind value | Description                                                                         | Adapters that emit it    |
-| ------------------- | ---------- | ----------------------------------------------------------------------------------- | ------------------------ |
-| `InitEvent`         | 1          | Session started; carries `SessionID`, `Model`, `ToolNames`, `CLIVersion`            | Claude, Gemini, OpenCode |
-| `TextEvent`         | 2          | Incremental text delta from the model (`Delta string`)                              | All                      |
-| `ThinkingEvent`     | 3          | Extended thinking delta (`Delta string`)                                            | Claude                   |
-| `ToolStartEvent`    | 4          | Tool invocation started; carries `ToolName`, `CallID`, `Input []byte`               | Claude, Gemini, OpenCode |
-| `ToolEndEvent`      | 5          | Tool invocation completed; carries `Output string`, `IsError bool`                  | Claude, Gemini, OpenCode |
-| `TurnCompleteEvent` | 6          | Model turn finished; carries `InputTokens`, `OutputTokens`, `CostUSD`, `StopReason` | All                      |
-| `ErrorEvent`        | 7          | Backend error; `Fatal=true` means the stream is terminated                          | All                      |
-| `RawEvent`          | 99         | Backend-specific event with no standard mapping; raw JSON in `RawJSON []byte`       | All                      |
+| Event type          | Kind value | Description                                                                                  | Adapters that emit it    |
+| ------------------- | ---------- | -------------------------------------------------------------------------------------------- | ------------------------ |
+| `InitEvent`         | 1          | Session started; carries `SessionID`, `Model`, `ToolNames`, `CLIVersion`                     | Claude, Gemini, OpenCode |
+| `TextEvent`         | 2          | Incremental text delta from the model (`Delta string`)                                       | All                      |
+| `ThinkingEvent`     | 3          | Extended thinking delta (`Delta string`)                                                     | Claude                   |
+| `ToolStartEvent`    | 4          | Tool invocation started; carries `ToolName`, `CallID`, `Input []byte`, `Source`, `MCPServer` | Claude, Gemini, OpenCode |
+| `ToolEndEvent`      | 5          | Tool invocation completed; carries `ToolName`, `CallID`, `Output string`, `IsError bool`     | Claude, Gemini, OpenCode |
+| `TurnCompleteEvent` | 6          | Model turn finished; carries `InputTokens`, `OutputTokens`, `CostUSD`, `StopReason`          | All                      |
+| `ErrorEvent`        | 7          | Backend error; `Fatal=true` means the stream is terminated                                   | All                      |
+| `RawEvent`          | 99         | Backend-specific event with no standard mapping; raw JSON in `RawJSON []byte`                | All                      |
 
 Consume events with a type switch:
 
@@ -318,7 +302,6 @@ Helper functions `xagent.CollectText` and `xagent.CollectResult` handle the comm
   - OpenAI Codex CLI: https://github.com/openai/codex
   - Gemini CLI: https://github.com/google-gemini/gemini-cli
   - OpenCode: https://github.com/sst/opencode
-- DockerExecutor requires `docker` on `PATH` and a running Docker daemon
 
 ## License
 

agent.go

@@ -41,12 +41,4 @@ type Capabilities struct {
 	SessionResume bool
 	// ForkSession indicates that the agent supports forking sessions via SessionConfig.ForkSession.
 	ForkSession bool
-	// Daemon indicates that the agent runs as a long-lived background server process.
-	Daemon bool
-	// StructuredOutput indicates that the agent supports JSON output schemas.
-	StructuredOutput bool
-	// MultiModal indicates that the agent accepts non-text inputs (e.g. images).
-	MultiModal bool
-	// ExtendedThinking indicates that the agent supports explicit reasoning / thinking traces.
-	ExtendedThinking bool
 }

claude/args.go

@@ -51,14 +51,6 @@ func buildArgs(cfg xagent.SessionConfig, prompt string, resumeID string, fork bo
 		args = append(args, "--max-turns", strconv.Itoa(cfg.MaxTurns))
 	}
 
-	if len(cfg.OutputSchema) > 0 {
-		args = append(args, "--output-schema", string(cfg.OutputSchema))
-	}
-
-	if cfg.ReasoningEffort != "" && cfg.ReasoningEffort != xagent.ReasoningNone {
-		args = append(args, "--reasoning-effort", string(cfg.ReasoningEffort))
-	}
-
 	if cfg.MCPConfig != nil && len(cfg.MCPConfig.Servers) > 0 {
 		mcpJSON, err := json.Marshal(buildMCPConfigJSON(cfg.MCPConfig))
 		if err == nil {

claude/claude.go

@@ -108,14 +108,12 @@ func (a *Agent) Name() string {
 	return "claude"
 }
 
+// Capabilities returns the feature flags supported by claude CLI 2.1.x.
 func (a *Agent) Capabilities() xagent.Capabilities {
 	return xagent.Capabilities{
-		Streaming:        true,
-		SessionResume:    true,
-		ForkSession:      true,
-		Daemon:           false,
-		StructuredOutput: true,
-		ExtendedThinking: true,
+		Streaming:     true,
+		SessionResume: true,
+		ForkSession:   true,
 	}
 }
 

claude/parser.go

@@ -114,13 +114,18 @@ func mapEvent(obj map[string]any, raw []byte) []xagent.Event {
 		}
 	case "result":
 		usage, _ := obj["usage"].(map[string]any)
-		return []xagent.Event{xagent.TurnCompleteEvent{
+		out := make([]xagent.Event, 0, 2)
+		if text := toString(obj["result"]); text != "" {
+			out = append(out, xagent.TextEvent{Delta: text, Timestamp: now})
+		}
+		out = append(out, xagent.TurnCompleteEvent{
 			InputTokens:  toInt(usage["input_tokens"]),
 			OutputTokens: toInt(usage["output_tokens"]),
 			CostUSD:      toFloat(obj["total_cost_usd"]),
 			StopReason:   toString(obj["stop_reason"]),
 			Timestamp:    now,
-		}}
+		})
+		return out
 	case "tool_result":
 		return []xagent.Event{xagent.ToolEndEvent{
 			ToolName:  toString(obj["name"]),

claude/session.go

@@ -64,8 +64,48 @@ func (s *session) Send(ctx context.Context, prompt string) (xagent.Stream, error
 		proc.Stdin = nil
 	}
 
+	// statefulMapLine suppresses the duplicate TextEvent that claude writes into the
+	// final 'result' line when text was already delivered via streaming 'assistant'
+	// events (normal mode). In plan mode no assistant TextEvents are emitted, so the
+	// 'result' line text is kept as the sole source.
+	var assistantTextSeen bool
+	statefulMapLine := func(line []byte) []xagent.Event {
+		events := mapLine(line)
+
+		// Single pass: detect result line and text events simultaneously.
+		var isResultLine, hasText bool
+		for _, e := range events {
+			switch e.(type) {
+			case xagent.TurnCompleteEvent:
+				isResultLine = true
+			case xagent.TextEvent:
+				hasText = true
+			}
+		}
+
+		if !isResultLine {
+			if hasText {
+				assistantTextSeen = true
+			}
+			return events
+		}
+
+		// result line: drop its TextEvent only when assistant streaming already delivered text.
+		if !assistantTextSeen {
+			return events
+		}
+		out := make([]xagent.Event, 0, len(events))
+		for _, e := range events {
+			if _, ok := e.(xagent.TextEvent); ok {
+				continue // suppress duplicate
+			}
+			out = append(out, e)
+		}
+		return out
+	}
+
 	scanner := ndjson.NewScanner(proc.Stdout)
-	return xagent.NewProcessStream(proc, scanner, mapLine,
+	return xagent.NewProcessStream(proc, scanner, statefulMapLine,
 		xagent.WithOnInit(func(init xagent.InitEvent) {
 			if init.SessionID != "" {
 				s.mu.Lock()

codex/codex.go

@@ -66,7 +66,7 @@ func WithBinaryPath(path string) Option {
 func (a *Agent) Name() string { return "codex" }
 
 func (a *Agent) Capabilities() xagent.Capabilities {
-	return xagent.Capabilities{Streaming: true, SessionResume: true, Daemon: true, StructuredOutput: true}
+	return xagent.Capabilities{Streaming: true, SessionResume: true}
 }
 
 func (a *Agent) Validate(ctx context.Context) error {