feat(coding): add workspace coding sessions

Author: XiaoConstantine

README.md

@@ -9,8 +9,8 @@ Maestro is an AI code review and repository analysis assistant built on top of `
 │                               USER INTERFACE                                │
 │                                                                              │
 │  CLI / TUI                                                                  │
-│  • PR review                                                                │
-│  • /ask repository questions                                                │
+│  • workspace coding sessions (ls/read/write/edit; bash opt-in)               │
+│  • PR review and /ask repository questions                                  │
 │  • optional review artifact + skill-store loading                           │
 └──────────────────────────────────────┬───────────────────────────────────────┘
                                        │
@@ -19,8 +19,8 @@ Maestro is an AI code review and repository analysis assistant built on top of `
 │                              MAESTRO SERVICE                                │
 │                                                                              │
 │  Root CLI + TUI routing                                                     │
-│  • review path                                                              │
-│  • ask / overview path                                                      │
+│  • coding-agent path with typed lifecycle events                            │
+│  • review and ask / overview paths                                          │
 │  • model and provider wiring                                                │
 │  • ACE + persisted skill integration                                        │
 └───────────────┬───────────────────────────────────────┬──────────────────────┘
@@ -69,6 +69,7 @@ Maestro is an AI code review and repository analysis assistant built on top of `
 - **Guideline Integration**: review runs can use cached guidelines and repository-aware context.
 - **Artifact-Aware Runtime**: live review runs can load tuned review artifacts and persisted skill stores.
 - **Repository Ask Support**: Maestro can answer codebase questions in addition to reviewing PRs.
+- **Coding Sessions**: Natural-language TUI input runs a workspace-scoped native agent with `ls`, `read`, `write`, and `edit`; unrestricted `bash` requires explicit `--allow-coding-bash`. `/ask` remains read-only QA.
 
 ### **Intelligent Review Pipeline**
 - **Specialized PR Review Agent**: Maestro uses a dedicated Go review path rather than a generic chat wrapper.
@@ -83,7 +84,9 @@ Maestro is an AI code review and repository analysis assistant built on top of `
 
 ### **Terminal UI (TUI v2)**
 - **Interactive Mode**: the root command still launches the modern interactive interface when no PR is provided.
-- **Slash-Command Workflow**: Maestro supports review and ask-style interaction patterns.
+- **Coding-Agent Workflow**: Natural-language prompts can inspect and edit the cloned workspace while typed run/turn/tool events update progress; shell verification is explicit opt-in.
+- **Slash-Command Workflow**: `/ask`, `/review`, session, and subagent commands remain explicit specialist paths.
+- **Cancellation**: Escape cancels the active coding run.
 - **Shared Runtime Wiring**: the same service layer backs both direct CLI review and interactive usage.
 
 ### **Semantic Code Search (Sgrep)**
@@ -219,6 +222,14 @@ The repo still contains ACE and RLM-related runtime wiring, but the most importa
 ### **Model Selection**
 
 ```bash
+# Interactive coding session (natural prompts edit the cloned workspace; /ask is read-only QA)
+go run . --interactive --model google:gemini-2.5-flash --owner XiaoConstantine --repo dspy-go
+
+# Non-interactive coding-session probe
+go run ./cmd/maestro-probe --strategy coding --allow-coding-bash --repo-path /path/to/repo \
+  --question "Inspect the failing test, fix it, and run the focused test" \
+  --model google:gemini-2.5-flash
+
 # Gemini
 go run . --model google:gemini-2.5-flash --owner XiaoConstantine --repo dspy-go --pr 291
 

cmd/maestro-probe/main.go

@@ -90,12 +90,13 @@ func run() error {
 		rlmTargetedArtifactsPath string
 		timeout                  time.Duration
 		verbose                  bool
+		allowCodingBash          bool
 	)
 
 	flag.Usage = func() {
 		fmt.Fprintf(flag.CommandLine.Output(), "Usage: maestro-probe --question <question> [flags]\n\n")
-		fmt.Fprintf(flag.CommandLine.Output(), "Runs MaestroService.ProcessRequest(RequestAsk) against a local repository and prints the response metadata as JSON.\n")
-		fmt.Fprintf(flag.CommandLine.Output(), "Scope: ask-side verification only; this does not exercise the PR review/RLM review path.\n\n")
+		fmt.Fprintf(flag.CommandLine.Output(), "Runs a Maestro ask or coding request against a local repository and prints response metadata as JSON.\n")
+		fmt.Fprintf(flag.CommandLine.Output(), "Use --strategy coding for workspace tools; PR review is not exercised.\n\n")
 		flag.PrintDefaults()
 	}
 
@@ -109,12 +110,13 @@ func run() error {
 	flag.StringVar(&modelConfig, "model-config", "", "Additional model configuration")
 	flag.StringVar(&apiKey, "api-key", "", "API key for external model providers")
 	flag.StringVar(&baseURL, "base-url", "", "Optional base URL override")
-	flag.StringVar(&strategy, "strategy", "", "Optional ask strategy override: native, rlm, or rlm-targeted")
+	flag.StringVar(&strategy, "strategy", "", "Execution strategy: native, rlm, rlm-targeted, or coding")
 	flag.StringVar(&memoryPath, "memory-path", "", "Optional Maestro memory path; defaults under /tmp")
 	flag.StringVar(&rlmOverviewArtifactsPath, "rlm-overview-artifact", "", "Optional RLM overview optimized program path")
 	flag.StringVar(&rlmTargetedArtifactsPath, "rlm-targeted-ask-artifact", "", "Optional RLM targeted ask optimized program path")
 	flag.DurationVar(&timeout, "timeout", 5*time.Minute, "Request timeout")
 	flag.BoolVar(&verbose, "verbose", false, "Enable debug logging to stderr")
+	flag.BoolVar(&allowCodingBash, "allow-coding-bash", false, "Allow unrestricted shell commands for --strategy coding")
 	flag.Parse()
 
 	if strings.TrimSpace(question) == "" {
@@ -179,7 +181,8 @@ func run() error {
 	core.GlobalConfig.DefaultLLM = defaultLLM
 
 	previousStrategy, hadStrategy := os.LookupEnv("MAESTRO_FORCE_ASK_STRATEGY")
-	if strategy = strings.TrimSpace(strategy); strategy != "" {
+	strategy = strings.TrimSpace(strategy)
+	if strategy != "" && strategy != "coding" {
 		if err := os.Setenv("MAESTRO_FORCE_ASK_STRATEGY", strategy); err != nil {
 			return fmt.Errorf("set ask strategy: %w", err)
 		}
@@ -195,6 +198,7 @@ func run() error {
 		Owner:                       owner,
 		Repo:                        repo,
 		BudgetManager:               budgetManager,
+		AllowCodingBash:             allowCodingBash,
 	}, nil)
 	if err != nil {
 		return fmt.Errorf("create service: %w", err)
@@ -206,12 +210,13 @@ func run() error {
 	}()
 	service.SetReviewAgent(&localReviewAgent{repoPath: resolvedRepoPath, status: types.NewIndexingStatus()})
 
-	response, err := service.ProcessRequest(ctx, orchestration.Request{
-		Type:     orchestration.RequestAsk,
-		Question: question,
-	})
+	request := orchestration.Request{Type: orchestration.RequestAsk, Question: question}
+	if strategy == "coding" {
+		request = orchestration.Request{Type: orchestration.RequestCoding, Prompt: question}
+	}
+	response, err := service.ProcessRequest(ctx, request)
 	if err != nil {
-		return fmt.Errorf("process ask request: %w", err)
+		return fmt.Errorf("process %s request: %w", request.Type, err)
 	}
 
 	output := probeOutput{

docs/coding_session.md

@@ -0,0 +1,68 @@
+# Maestro Coding Session
+
+Maestro's interactive default is a workspace coding agent. Natural-language TUI input runs a provider-neutral `dspy-go` native agent against the cloned repository; `/ask` remains the read-only repository-QA route.
+
+## Architecture
+
+```text
+terminal.MaestroModel
+  -> terminal.MaestroBackend
+  -> orchestration.MaestroService
+  -> internal/coding.Session
+  -> native.Agent.ExecuteWithTrace
+```
+
+The boundaries mirror Tau/Pi:
+
+- `dspy-go/pkg/agents` owns the reusable execution loop, typed events, messages, and canonical traces.
+- `internal/coding.Session` owns Maestro's workspace tools, active-run cancellation, and session persistence configuration.
+- `internal/orchestration` selects the cloned workspace and records trace usage.
+- `terminal` maps typed lifecycle events into Bubble Tea display progress.
+
+The frontend does not inspect provider responses or parse result maps.
+
+## Behavior
+
+A coding session registers these workspace-contained file tools by default:
+
+- `ls`
+- `read`
+- `write`
+- `edit`
+
+File tools reject paths outside the cloned repository workspace. Shell execution is disabled by default because setting a working directory is not a sandbox: shell commands can otherwise access absolute paths, `$HOME`, and the network. Pass `--allow-coding-bash` to opt into unrestricted `bash` with the workspace as its initial working directory.
+
+One run may mutate a session at a time. Overlapping prompts are rejected. Press **Esc** to cancel the active coding run. Run, turn, and tool lifecycle events update the TUI progress display. Output and accounting use the operation-scoped `ExecutionTrace` returned by `ExecuteWithTrace`, avoiding races against a mutable last-trace accessor.
+
+The active Maestro session name selects the native session id, so switching or creating a session selects separate persisted coding history.
+
+## Running
+
+```bash
+go run . --interactive \
+  --owner XiaoConstantine \
+  --repo dspy-go \
+  --model google:gemini-2.5-flash
+```
+
+Add `--allow-coding-bash` only when you trust the active model and accept unrestricted shell access.
+
+Enter a task such as:
+
+```text
+Inspect the failing tests, implement the smallest fix, and run the focused tests.
+```
+
+For a non-interactive smoke test:
+
+```bash
+go run ./cmd/maestro-probe \
+  --strategy coding \
+  --repo-path /path/to/repository \
+  --question "Create hello.txt and verify its contents" \
+  --model google:gemini-2.5-flash
+```
+
+## Current boundary
+
+This slice establishes the coding-session execution spine. Tau-level steering/follow-up queues, compaction, session-tree transcript rendering, project instruction discovery, skill/prompt pickers, model switching, and token-delta streaming remain follow-up frontend/session features. They should be added above `dspy-go`'s canonical contracts rather than by creating another execution loop.

internal/coding/session.go

@@ -0,0 +1,177 @@
+package coding
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"sync"
+
+	"github.com/XiaoConstantine/dspy-go/pkg/agents"
+	"github.com/XiaoConstantine/dspy-go/pkg/agents/native"
+	"github.com/XiaoConstantine/dspy-go/pkg/agents/sessionevent"
+	"github.com/XiaoConstantine/dspy-go/pkg/core"
+	"github.com/XiaoConstantine/dspy-go/pkg/tools/defaults"
+)
+
+var (
+	ErrRunActive     = errors.New("coding session already has an active run")
+	ErrSessionClosed = errors.New("coding session is closed")
+)
+
+type Config struct {
+	LLM          core.LLM
+	Workspace    string
+	SessionID    string
+	SessionStore sessionevent.SessionEventStore
+	SystemPrompt string
+	MaxTurns     int
+	AllowBash    bool
+}
+
+type Session struct {
+	workspace string
+	agent     *native.Agent
+	forwarder *eventForwarder
+
+	runMu   sync.Mutex
+	mu      sync.Mutex
+	stop    context.CancelFunc
+	runDone chan struct{}
+	closed  bool
+}
+
+func NewSession(cfg Config) (*Session, error) {
+	if cfg.LLM == nil {
+		return nil, fmt.Errorf("llm is required")
+	}
+	if strings.TrimSpace(cfg.Workspace) == "" {
+		return nil, fmt.Errorf("workspace is required")
+	}
+
+	toolset, err := defaults.NewToolset(defaults.Config{Root: cfg.Workspace})
+	if err != nil {
+		return nil, fmt.Errorf("create coding tools: %w", err)
+	}
+	forwarder := &eventForwarder{}
+	agent, err := native.NewAgent(cfg.LLM, native.Config{
+		MaxTurns:          cfg.MaxTurns,
+		SystemPrompt:      cfg.SystemPrompt,
+		SessionID:         strings.TrimSpace(cfg.SessionID),
+		SessionEventStore: cfg.SessionStore,
+		EventSink:         forwarder,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("create coding agent: %w", err)
+	}
+	for _, tool := range toolset.Tools() {
+		if tool.Name() == "bash" && !cfg.AllowBash {
+			continue
+		}
+		if err := agent.RegisterTool(tool); err != nil {
+			return nil, fmt.Errorf("register coding tool %s: %w", tool.Name(), err)
+		}
+	}
+
+	return &Session{workspace: toolset.Root(), agent: agent, forwarder: forwarder}, nil
+}
+
+func (s *Session) Workspace() string {
+	if s == nil {
+		return ""
+	}
+	return s.workspace
+}
+
+func (s *Session) Prompt(ctx context.Context, prompt string, sink agents.EventSink) (agents.AgentExecutionResult, error) {
+	if s == nil || s.agent == nil {
+		return agents.AgentExecutionResult{}, fmt.Errorf("coding session is not initialized")
+	}
+	if strings.TrimSpace(prompt) == "" {
+		return agents.AgentExecutionResult{}, fmt.Errorf("prompt is required")
+	}
+	if !s.runMu.TryLock() {
+		return agents.AgentExecutionResult{}, ErrRunActive
+	}
+	defer s.runMu.Unlock()
+
+	runCtx, cancel := context.WithCancel(ctx)
+	s.mu.Lock()
+	if s.closed {
+		s.mu.Unlock()
+		cancel()
+		return agents.AgentExecutionResult{}, ErrSessionClosed
+	}
+	done := make(chan struct{})
+	s.stop = cancel
+	s.runDone = done
+	s.mu.Unlock()
+	s.forwarder.Set(sink)
+	defer func() {
+		s.forwarder.Set(nil)
+		cancel()
+		s.mu.Lock()
+		s.stop = nil
+		s.runDone = nil
+		close(done)
+		s.mu.Unlock()
+	}()
+
+	return s.agent.ExecuteWithTrace(runCtx, map[string]any{"task": prompt})
+}
+
+func (s *Session) Close(ctx context.Context) error {
+	if s == nil {
+		return nil
+	}
+	s.mu.Lock()
+	s.closed = true
+	cancel := s.stop
+	done := s.runDone
+	if cancel != nil {
+		cancel()
+	}
+	s.mu.Unlock()
+	if done == nil {
+		return nil
+	}
+	select {
+	case <-done:
+		return nil
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+}
+
+func (s *Session) Cancel() bool {
+	if s == nil {
+		return false
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.stop == nil {
+		return false
+	}
+	s.stop()
+	return true
+}
+
+type eventForwarder struct {
+	mu   sync.RWMutex
+	sink agents.EventSink
+}
+
+func (f *eventForwarder) Set(sink agents.EventSink) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.sink = sink
+}
+
+func (f *eventForwarder) EmitEvent(ctx context.Context, event agents.ExecutionEvent) {
+	f.mu.RLock()
+	sink := f.sink
+	f.mu.RUnlock()
+	if sink != nil {
+		sink.EmitEvent(ctx, event)
+	}
+}