feat: add interactive command mode, :help/:usage commands, and token usage tracking

.gitignore

@@ -1,7 +1,7 @@
-# Binaries
-# Go build artifacts
+# Binaries & build artifacts
 bin/
 build/
+dist/
 *.exe
 *.dll
 *.so
@@ -12,35 +12,32 @@ build/
 /picoclaw-test
 cmd/**/workspace
 
-# Picoclaw specific
-
-# PicoClaw
+# PicoClaw workspace & config
 .picoclaw/
 config.json
 sessions/
-build/
-
-# Coverage
+cmd/picoclaw/workspace
 
-# Secrets & Config (keep templates, ignore actual secrets)
+# Secrets
 .env
 config/config.json
 
-# Test
+# Coverage
 coverage.txt
 coverage.html
 
 # OS
 .DS_Store
 
-# Ralph workspace
-ralph/
-.ralph/
-tasks/
-
-# Editors
+# Editors & tools
 .vscode/
 .idea/
+.claude/
 
-# Added by goreleaser init:
-dist/
+# Task tracking
+TASKS.md
+
+# Legacy
+ralph/
+.ralph/
+tasks/

pkg/agent/cmd_helpers_test.go

@@ -0,0 +1,104 @@
+package agent
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestResolveEditPath_AbsoluteBlocked(t *testing.T) {
+	workspace := t.TempDir()
+	_, err := resolveEditPath("/etc/passwd", workspace, workspace)
+	if err == nil {
+		t.Fatal("Expected absolute path outside workspace to be blocked")
+	}
+}
+
+func TestResolveEditPath_TildeIsWorkspace(t *testing.T) {
+	workspace := t.TempDir()
+	// Create a file so the path resolves
+	os.WriteFile(filepath.Join(workspace, "test.txt"), []byte("hi"), 0o644)
+
+	path, err := resolveEditPath("~/test.txt", workspace, workspace)
+	if err != nil {
+		t.Fatalf("Unexpected error: %v", err)
+	}
+	expected := filepath.Join(workspace, "test.txt")
+	if path != expected {
+		t.Errorf("Expected %s, got %s", expected, path)
+	}
+}
+
+func TestResolveEditPath_BareTildeIsWorkspace(t *testing.T) {
+	workspace := t.TempDir()
+	path, err := resolveEditPath("~", workspace, workspace)
+	if err != nil {
+		t.Fatalf("Unexpected error: %v", err)
+	}
+	if path != workspace {
+		t.Errorf("Expected %s, got %s", workspace, path)
+	}
+}
+
+func TestResolveEditPath_TraversalBlocked(t *testing.T) {
+	workspace := t.TempDir()
+	_, err := resolveEditPath("../../etc/passwd", workspace, workspace)
+	if err == nil {
+		t.Fatal("Expected path traversal to be blocked")
+	}
+}
+
+func TestResolveEditPath_SymlinkBlocked(t *testing.T) {
+	root := t.TempDir()
+	workspace := filepath.Join(root, "workspace")
+	os.MkdirAll(workspace, 0o755)
+	secret := filepath.Join(root, "secret.txt")
+	os.WriteFile(secret, []byte("secret"), 0o644)
+	link := filepath.Join(workspace, "link.txt")
+	if err := os.Symlink(secret, link); err != nil {
+		t.Skip("symlinks not supported")
+	}
+	_, err := resolveEditPath("link.txt", workspace, workspace)
+	if err == nil {
+		t.Fatal("Expected symlink escape to be blocked")
+	}
+}
+
+func TestResolveEditPath_ValidRelative(t *testing.T) {
+	workspace := t.TempDir()
+	subdir := filepath.Join(workspace, "subdir")
+	os.MkdirAll(subdir, 0o755)
+	testFile := filepath.Join(subdir, "test.txt")
+	os.WriteFile(testFile, []byte("content"), 0o644)
+
+	path, err := resolveEditPath("subdir/test.txt", workspace, workspace)
+	if err != nil {
+		t.Fatalf("Unexpected error: %v", err)
+	}
+	if path != testFile {
+		t.Errorf("Expected %s, got %s", testFile, path)
+	}
+}
+
+func TestShortenHomePath(t *testing.T) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		t.Skip("cannot get home dir")
+	}
+
+	tests := []struct {
+		input    string
+		expected string
+	}{
+		{home, "~"},
+		{filepath.Join(home, "projects"), "~/projects"},
+		{"/tmp/other", "/tmp/other"},
+	}
+
+	for _, tt := range tests {
+		result := shortenHomePath(tt.input)
+		if result != tt.expected {
+			t.Errorf("shortenHomePath(%q) = %q, want %q", tt.input, result, tt.expected)
+		}
+	}
+}

pkg/agent/instance.go

@@ -4,6 +4,7 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
+	"sync/atomic"
 
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/providers"
@@ -31,6 +32,21 @@ type AgentInstance struct {
 	Subagents      *config.SubagentsConfig
 	SkillsFilter   []string
 	Candidates     []providers.FallbackCandidate
+
+	// Accumulated token usage counters (atomic for concurrent safety)
+	TotalPromptTokens     atomic.Int64
+	TotalCompletionTokens atomic.Int64
+	TotalRequests         atomic.Int64
+}
+
+// AddUsage accumulates token usage from a single LLM response.
+func (a *AgentInstance) AddUsage(usage *providers.UsageInfo) {
+	if usage == nil {
+		return
+	}
+	a.TotalPromptTokens.Add(int64(usage.PromptTokens))
+	a.TotalCompletionTokens.Add(int64(usage.CompletionTokens))
+	a.TotalRequests.Add(1)
 }
 
 // NewAgentInstance creates an agent instance from config.