feat: add a call stack data structure

Signed-off-by: Donnie Adams <[email protected]>

Author: thedadams

callstack.go

@@ -0,0 +1,28 @@
+package gptscript
+
+type CallStack struct {
+	Call     CallFrame   `json:"call"`
+	SubCalls []CallStack `json:"subCalls"`
+}
+
+func newCallStack(run *Run, parentID string) []CallStack {
+	if len(run.callsByParentIDs[parentID]) == 0 {
+		return nil
+	}
+
+	var callStack []CallStack
+	callIDs := run.callsByParentIDs[parentID]
+	for len(callIDs) != 0 {
+		callID := callIDs[0]
+		callIDs = callIDs[1:]
+
+		cs := CallStack{
+			Call:     run.calls[callID],
+			SubCalls: newCallStack(run, callID),
+		}
+
+		callStack = append(callStack, cs)
+	}
+
+	return callStack
+}

client_test.go

@@ -188,7 +188,6 @@ func TestEvaluateWithToolList(t *testing.T) {
 		},
 		&ToolDef{
 			Name:        "echo",
-			Tools:       []string{"sys.exec"},
 			Description: "Echoes the input",
 			Args: map[string]string{
 				"input": "The string input to echo",
@@ -212,6 +211,60 @@ func TestEvaluateWithToolList(t *testing.T) {
 	}
 }
 
+func TestCallStack(t *testing.T) {
+	shebang := "#!/bin/bash"
+	if runtime.GOOS == "windows" {
+		shebang = "#!/usr/bin/env powershell.exe"
+	}
+	tools := []fmt.Stringer{
+		&ToolDef{
+			Tools:        []string{"echo"},
+			Instructions: "echo hello there",
+		},
+		&ToolDef{
+			Name:        "echo",
+			Description: "Echoes the input",
+			Args: map[string]string{
+				"input": "The string input to echo",
+			},
+			Instructions: shebang + "\n echo ${input}",
+		},
+	}
+
+	run, err := c.Evaluate(context.Background(), Options{}, tools...)
+	if err != nil {
+		t.Errorf("Error executing tool: %v", err)
+	}
+
+	// Wait for the run to complete.
+	_, err = run.Text()
+	if err != nil {
+		t.Fatalf("Error waiting for run to finish: %v", err)
+	}
+
+	cs := run.CallStack()
+
+	if cs == nil {
+		t.Fatalf("No call stack")
+	}
+
+	if cs.Call.ID == "" {
+		t.Errorf("Call ID is empty")
+	}
+
+	if len(cs.SubCalls) != 1 {
+		t.Fatalf("Call stack contains %d subcalls", len(cs.SubCalls))
+	}
+
+	if cs.SubCalls[0].Call.ParentID != cs.Call.ID {
+		t.Errorf("Unexpected call stack sub call parent: %s != %s", cs.SubCalls[0].Call.ParentID, cs.Call.ID)
+	}
+
+	if cs.SubCalls[0].Call.Tool.Name != "echo" {
+		t.Errorf("Unexpected tool name: %s", cs.SubCalls[0].Call.Tool.Name)
+	}
+}
+
 func TestEvaluateWithToolListAndSubTool(t *testing.T) {
 	shebang := "#!/bin/bash"
 	if runtime.GOOS == "windows" {

run.go

@@ -11,6 +11,7 @@ import (
 	"maps"
 	"net/http"
 	"os/exec"
+	"slices"
 	"strconv"
 	"sync"
 )
@@ -29,6 +30,7 @@ type Run struct {
 
 	callsLock         sync.RWMutex
 	calls             map[string]CallFrame
+	callsByParentIDs  map[string][]string
 	parentCallFrameID string
 	rawOutput         map[string]any
 	output, errput    string
@@ -82,6 +84,19 @@ func (r *Run) ParentCallFrame() (CallFrame, bool) {
 	return r.calls[r.parentCallFrameID], true
 }
 
+// CallStack returns a nested version of the current call stack of the run.
+func (r *Run) CallStack() *CallStack {
+	r.callsLock.RLock()
+	defer r.callsLock.RUnlock()
+
+	cs := newCallStack(r, "")
+	if len(cs) == 0 {
+		return nil
+	}
+
+	return &cs[0]
+}
+
 // ErrorOutput returns the stderr output of the gptscript.
 // Should only be called after Bytes or Text has returned an error.
 func (r *Run) ErrorOutput() string {
@@ -166,6 +181,10 @@ func (r *Run) NextChat(ctx context.Context, input string) (*Run, error) {
 }
 
 func (r *Run) request(ctx context.Context, payload any) (err error) {
+	if r.state.IsTerminal() {
+		return fmt.Errorf("run is in terminal state and cannot be run again: state %q", r.state)
+	}
+
 	var (
 		req               *http.Request
 		url               = fmt.Sprintf("%s/%s", r.url, r.requestPath)
@@ -228,6 +247,11 @@ func (r *Run) request(ctx context.Context, payload any) (err error) {
 			r.lock.Unlock()
 		}()
 
+		r.callsLock.Lock()
+		r.calls = make(map[string]CallFrame)
+		r.callsByParentIDs = make(map[string][]string)
+		r.callsLock.Unlock()
+
 		for n := 0; n != 0 || err == nil; n, err = resp.Body.Read(buf) {
 			for _, line := range bytes.Split(bytes.TrimSpace(append(frag, buf[:n]...)), []byte("\n\n")) {
 				line = bytes.TrimSpace(bytes.TrimPrefix(line, []byte("data: ")))
@@ -316,6 +340,8 @@ func (r *Run) request(ctx context.Context, payload any) (err error) {
 						if r.parentCallFrameID == "" && event.Call.ParentID == "" {
 							r.parentCallFrameID = event.Call.ID
 						}
+
+						r.appendCallIDToParentID(event.Call.ID, event.Call.ParentID)
 						r.callsLock.Unlock()
 					}
 
@@ -353,6 +379,12 @@ func (r *Run) request(ctx context.Context, payload any) (err error) {
 	return nil
 }
 
+func (r *Run) appendCallIDToParentID(callID, parentID string) {
+	if !slices.Contains(r.callsByParentIDs[parentID], callID) {
+		r.callsByParentIDs[parentID] = append(r.callsByParentIDs[parentID], callID)
+	}
+}
+
 type RunState string
 
 func (rs RunState) IsTerminal() bool {