Release/v0.0.5 (#11)

* refactor bash tool

* refactor file tools

* add agent tool

* refactor human tool

* remove session tracker from file edit tool

* refactor the skill as a true tool

* refactor: reorganize tool-related code into separate file and clean up unused definitions

* refactor: enhance error handling for maximum iterations in agent loop

* refactor: clean up unused imports and remove temporary file writing

* docs: update README and tool documentation to include new agent tool and enhanced descriptions

* fix

Author: henomis

Makefile

@@ -10,10 +10,10 @@ GOLANGCI_LINT := golangci-lint
 DOCKER_COMPOSE := docker compose
 E2E_OPENAI_BASE_URL ?= http://localhost:11434/v1
 E2E_OPENAI_API_KEY ?= ollama
-E2E_OPENAI_MODEL ?= minimax-m2.7:cloud
+E2E_OPENAI_MODEL ?= deepseek-v3.1:671b-cloud
 E2E_ANTHROPIC_BASE_URL ?= http://localhost:11434
 E2E_ANTHROPIC_AUTH_TOKEN ?= ollama
-E2E_ANTHROPIC_MODEL ?= minimax-m2.7:cloud
+E2E_ANTHROPIC_MODEL ?= deepseek-v3.1:671b-cloud
 E2E_EMBEDDING_MODEL ?= nomic-embed-text
 
 # Default target

README.md

@@ -104,9 +104,11 @@ Phero is organized into focused packages, each solving a specific problem:
 - **`mcp`** Model Context Protocol adapter for external tool integration
 - **`a2a`** Agent-to-Agent (A2A) protocol — expose agents as HTTP servers or call remote agents as tools
 - **`trace`** Typed observability events; `trace/text` for human-readable colorized output; `trace/jsonfile` for NDJSON file logging; `trace.NewLLM` for raw LLM call wrapping
-- **`tool/file`** File viewing and editing helpers (`view`, `create_file` with optional no-overwrite, `str_replace`)
-- **`tool/bash`** Bash command execution with blocklist, allowlist, timeout, and safe-mode guardrails
-- **`tool/human`** Human-in-the-loop input collection
+- **`tool/agent`** Create and run a sub-agent at runtime as a delegated tool
+- **`tool/file`** Filesystem tools (`read`, `write`, `edit`, `glob`, `grep`)
+- **`tool/bash`** Bash command execution with guardrails (blocklist, allowlist, timeout, safe mode) and background execution (`RunInBackground`, `bash_output`, `kill_shell`)
+- **`tool/human`** Structured user-interaction checkpoints; caller provides the interactor via `WithInteractor`
+- **`tool/skill`** Dispatcher-style SKILL.md loader tool that expands instructions in the main conversation
 
 
 
@@ -133,7 +135,7 @@ Comprehensive examples are included in the [`examples/`](examples/) directory:
 | [Parallel Research](examples/parallel-research/) | Fan-out/fan-in workflow that runs multiple specialist researchers in parallel and merges their findings |
 | [Prompt Chaining](examples/prompt-chaining/) | Sequential multi-step prompting with a programmatic gate between stages |
 | [RAG Chatbot](examples/rag-chatbot/) | Terminal chatbot with semantic search over local documents using Qdrant |
-| [Skill](examples/skills/) | Discover SKILL.md files and expose them as callable agent tools |
+| [Skill](examples/skills/) | Use the `tool/skill` dispatcher to load SKILL.md instructions into the current conversation |
 | [Social Simulation](examples/social-simulation/) | Multi-agent social simulation with persona-driven actors and emergent interactions |
 | [MCP Integration](examples/mcp/) | Run an MCP server as a subprocess and expose its tools to agents |
 | [Playwright MCP](examples/playwright-mcp/) | Connect browser automation tools through MCP and orchestrate them from an agent |

agent/agent.go

@@ -152,7 +152,9 @@ func (a *Agent) SetMemory(mem memory.Memory) {
 
 // SetMaxIterations sets a maximum number of iterations for the agent loop.
 //
-// If the limit is reached, Run() returns an error. By default, there is no limit.
+// If the limit is reached, Run() returns ErrMaxIterationsReached together with
+// any partial text the model produced so far (the result may be non-nil even
+// when the error is set). By default, there is no limit.
 func (a *Agent) SetMaxIterations(maxIterations int) {
 	a.maxIterations = maxIterations
 }
@@ -172,6 +174,10 @@ func (a *Agent) SetTracer(t trace.Tracer) {
 // The agent calls the LLM, executes any requested tool calls, and repeats until
 // the model returns a message without tool calls.
 //
+// If the maximum iterations limit is reached, the function returns
+// ErrMaxIterationsReached together with any partial text the model produced
+// (result may be non-nil even when err is set — use errors.Is to distinguish).
+//
 // If the run succeeds but saving the session to memory fails, the result is
 // still returned together with the save error joined via errors.Join.
 func (a *Agent) Run(ctx context.Context, parts ...llm.ContentPart) (result *Result, err error) {
@@ -225,7 +231,7 @@ func (a *Agent) Run(ctx context.Context, parts ...llm.ContentPart) (result *Resu
 	for {
 		iteration++
 		if a.maxIterations > 0 && iteration > a.maxIterations {
-			return nil, ErrMaxIterationsReached
+			return partialResultFromSession(session), ErrMaxIterationsReached
 		}
 
 		a.tracer.Trace(trace.AgentIterationEvent{
@@ -253,6 +259,28 @@ func (a *Agent) Run(ctx context.Context, parts ...llm.ContentPart) (result *Resu
 	}
 }
 
+// partialResultFromSession scans the session backwards and returns a Result
+// built from the last assistant message that contains at least one text part.
+// Returns nil if no such message exists.
+func partialResultFromSession(session []llm.Message) *Result {
+	for i := len(session) - 1; i >= 0; i-- {
+		msg := session[i]
+		if msg.Role != llm.RoleAssistant {
+			continue
+		}
+		textParts := make([]llm.ContentPart, 0, len(msg.Parts))
+		for _, p := range msg.Parts {
+			if p.Type == llm.ContentTypeText {
+				textParts = append(textParts, p)
+			}
+		}
+		if len(textParts) > 0 {
+			return &Result{Parts: textParts}
+		}
+	}
+	return nil
+}
+
 // saveSession saves the conversation messages to memory, if memory is configured.
 func (a *Agent) saveSession(ctx context.Context, messages []llm.Message, sessionIndex int, stats *runStats) error {
 	if a.memory == nil {

agent/errors.go

@@ -26,7 +26,8 @@ var (
 	ErrDescriptionRequired = errors.New("agent description is required")
 	// ErrNameRequired is returned when creating an agent with an empty name.
 	ErrNameRequired = errors.New("agent name is required")
-	// ErrMaxIterationsReached is returned when the agent loop reaches the maximum number of iterations.
+	// ErrMaxIterationsReached is returned when the agent loop reaches the maximum number of
+	// iterations. Run() will still return any partial text result alongside this error.
 	ErrMaxIterationsReached = errors.New("maximum iterations reached")
 	// ErrSessionSaveFailed is returned when the memory save after a successful run fails.
 	ErrSessionSaveFailed = errors.New("session save failed")

examples/human-in-the-loop/README.md

@@ -11,9 +11,9 @@ goal
   ▼
 DevOps Assistant
   │
-  ├─► ask_human("I plan to create a Dockerfile. Approve?")
+  ├─► user_interaction({ structured approval question })
   │         │
-  │    human response
+  │    structured user answer
   │         │
   │    approved? ──yes──► simulate_action("create Dockerfile")
   │         │
@@ -26,10 +26,11 @@ DevOps Assistant
 ```
 
 Key properties:
-- **`tool/human`** — the built-in `ask_human` tool presents a question on stdout and reads the answer from stdin.
+- **`tool/human`** — the built-in `user_interaction` tool validates a structured question payload (questions, options, multi-select flags) and returns structured answers.
+- **Host-provided interactor** — applications inject how answers are collected (CLI, web, IDE, etc.). In this example, a console callback renders options and reads stdin.
 - **Agent-controlled gate** — the agent itself decides when to ask; it is instructed never to simulate an action without prior approval.
 - **No hardcoded workflow** — the agent plans its own steps based on the goal; the human controls what actually runs.
-- **Interactive by design** — this example requires stdin interaction and is not suitable for CI.
+- **Interactive by design** — this sample callback uses stdin interaction and is not suitable for CI.
 
 ## Run
 
@@ -47,11 +48,13 @@ go run ./examples/human-in-the-loop \
   -goal "Set up infrastructure for a Python FastAPI service: virtual environment, Dockerfile, nginx config."
 ```
 
-When prompted, respond with:
-- `yes` / `ok` / `proceed` — approve the action
-- `no` / `skip` — skip this action
-- `stop` / `abort` — stop all remaining actions
-- Any freeform text — the agent will adjust accordingly
+When prompted, select an option label or number:
+- `Approve` / `1` — approve the action
+- `Skip` / `2` — skip this action
+- `Modify` / `3` — ask the agent to revise first
+- `Stop` / `4` — stop all remaining actions
+
+Optional free text can be provided as `other: <text>` in the same answer.
 
 ### Flags
 

examples/human-in-the-loop/main.go

@@ -15,10 +15,13 @@
 package main
 
 import (
+	"bufio"
 	"context"
 	"flag"
 	"fmt"
+	"io"
 	"os"
+	"strconv"
 	"strings"
 	"time"
 
@@ -39,6 +42,18 @@ type ActionOutput struct {
 	Status string `json:"status" jsonschema:"description=Outcome of the action: 'applied' or 'skipped'."`
 }
 
+type consoleInteractor struct {
+	reader *bufio.Reader
+	writer io.Writer
+}
+
+func newConsoleInteractor(reader io.Reader, writer io.Writer) *consoleInteractor {
+	return &consoleInteractor{
+		reader: bufio.NewReader(reader),
+		writer: writer,
+	}
+}
+
 func main() {
 	var goal string
 	var timeout time.Duration
@@ -108,7 +123,9 @@ func buildLLMFromEnv() (llm.LLM, string) {
 }
 
 func buildAgent(llmClient llm.LLM) (*agent.Agent, error) {
-	humanTool, err := human.New()
+	interactor := newConsoleInteractor(os.Stdin, os.Stdout)
+
+	humanTool, err := human.New(human.WithInteractor(interactor.Ask))
 	if err != nil {
 		return nil, err
 	}
@@ -125,21 +142,26 @@ func buildAgent(llmClient llm.LLM) (*agent.Agent, error) {
 	a, err := agent.New(llmClient, "DevOps Assistant", strings.TrimSpace(`You are a DevOps assistant helping a developer set up a new project.
 
 You have two tools:
-- ask_human: use this to propose an action and ask for the developer's approval BEFORE doing anything.
-- simulate_action: use this ONLY after the human has explicitly approved the action.
-
-Workflow for every action you intend to take:
-1. Call ask_human describing the action you plan to take and why.
-2. Read the human's response carefully.
-   - If they approve (e.g. "yes", "ok", "proceed", "accept"): call simulate_action.
-   - If they decline (e.g. "no", "skip", "skip it"): skip this action and move on.
-   - If they ask for a modification: adjust the action accordingly, then ask again before simulating.
-   - If they say "stop" or "abort": stop all remaining actions and summarise what was completed.
-3. Continue to the next action.
-
-At the end, summarise which actions were applied and which were skipped.
-
-Never simulate an action without explicit human approval.`))
+- user_interaction: use this to ask structured user questions before taking any consequential action.
+- simulate_action: use this only after explicit user approval.
+
+For each action you plan to execute, call user_interaction with exactly one question:
+- header: "Approval"
+- question: describe the action and end with a question mark.
+- multiSelect: false
+- options:
+	1) label "Approve" description "Proceed with the proposed action"
+	2) label "Skip" description "Skip this action"
+	3) label "Modify" description "User wants a modified version first"
+	4) label "Stop" description "Stop the remaining plan"
+
+Interpret the tool output from answers["Approval"]:
+- selection "Approve": call simulate_action.
+- selection "Skip": skip this action.
+- selection "Modify": revise action using the optional free-text field and ask again.
+- selection "Stop": stop all remaining actions and summarize.
+
+Never call simulate_action without an explicit "Approve" selection.`))
 	if err != nil {
 		return nil, err
 	}
@@ -166,3 +188,104 @@ func simulateAction(_ context.Context, in *ActionInput) (*ActionOutput, error) {
 
 	return &ActionOutput{Status: "applied"}, nil
 }
+
+// Ask presents structured questions and returns selected option labels.
+func (c *consoleInteractor) Ask(ctx context.Context, in *human.Input) (map[string]human.Answer, error) {
+	_ = ctx
+
+	answers := make(map[string]human.Answer, len(in.Questions))
+
+	for _, question := range in.Questions {
+		if _, err := fmt.Fprintf(c.writer, "\n[%s] %s\n", question.Header, question.Question); err != nil {
+			return nil, err
+		}
+		for idx, option := range question.Options {
+			if _, err := fmt.Fprintf(c.writer, "  %d) %s - %s\n", idx+1, option.Label, option.Description); err != nil {
+				return nil, err
+			}
+		}
+
+		if question.MultiSelect {
+			if _, err := fmt.Fprint(c.writer, "Select one or more options (comma separated labels or numbers). Optional free text: other: <text>\n> "); err != nil {
+				return nil, err
+			}
+		} else {
+			if _, err := fmt.Fprint(c.writer, "Select one option (label or number). Optional free text: other: <text>\n> "); err != nil {
+				return nil, err
+			}
+		}
+
+		line, err := c.reader.ReadString('\n')
+		if err != nil {
+			return nil, err
+		}
+
+		answer, err := parseAnswer(strings.TrimSpace(line), question)
+		if err != nil {
+			return nil, err
+		}
+
+		answers[question.Header] = answer
+	}
+
+	return answers, nil
+}
+
+func parseAnswer(raw string, question human.Question) (human.Answer, error) {
+	result := human.Answer{}
+	if raw == "" {
+		return result, nil
+	}
+
+	parts := strings.Split(raw, ",")
+	seen := map[string]struct{}{}
+
+	for _, part := range parts {
+		choice := strings.TrimSpace(part)
+		if choice == "" {
+			continue
+		}
+
+		if strings.HasPrefix(strings.ToLower(choice), "other:") {
+			result.Other = strings.TrimSpace(choice[len("other:"):])
+			continue
+		}
+
+		label, err := resolveOptionLabel(choice, question.Options)
+		if err != nil {
+			return human.Answer{}, err
+		}
+
+		normalized := strings.ToLower(label)
+		if _, exists := seen[normalized]; exists {
+			continue
+		}
+		seen[normalized] = struct{}{}
+		result.Selections = append(result.Selections, label)
+	}
+
+	if !question.MultiSelect && len(result.Selections) > 1 {
+		return human.Answer{}, fmt.Errorf("question %q allows only one selection", question.Header)
+	}
+
+	return result, nil
+}
+
+func resolveOptionLabel(choice string, options []human.Choice) (string, error) {
+	index, err := strconv.Atoi(choice)
+	if err == nil {
+		if index < 1 || index > len(options) {
+			return "", fmt.Errorf("invalid option index: %d", index)
+		}
+		return options[index-1].Label, nil
+	}
+
+	normalizedChoice := strings.ToLower(strings.TrimSpace(choice))
+	for _, option := range options {
+		if strings.ToLower(option.Label) == normalizedChoice {
+			return option.Label, nil
+		}
+	}
+
+	return "", fmt.Errorf("invalid option label: %q", choice)
+}

examples/skills/README.md

@@ -3,7 +3,7 @@
 This example demonstrates how to:
 
 - discover and parse local `SKILL.md` definitions
-- turn each skill into a callable tool for an `agent.Agent`
+- expose a single dispatcher tool for skill execution
 - let the agent combine a skill output with a file-writing tool
 
 It includes one skill: `get-random-quote`, which fetches a quote from https://zenquotes.io by running a small Go script.
@@ -58,9 +58,8 @@ and a file named `quote.html` will be created in the current directory.
 
 ## What it does
 
-- Creates a skills parser rooted at `./skills`.
-- Lists skill directories (each contains a `SKILL.md`).
-- Parses each `SKILL.md` and converts it into a tool via `skill.AsTool(...)`.
+- Creates a skill dispatcher rooted at `./skills`.
+- Exposes one `skill` tool via `tool/skill` and lets the agent choose a skill by name at runtime.
 - Adds an explicit file write tool (with an interactive validation prompt).
 - Runs the agent with: "create a web page containing a random quote, and save the html to a file called quote.html".