refactor: rename Path and PathStep to Address and AddressSegment

Change-Id: I689c9ef7799020f0e988fd724620641efb71ef80

Author: shentongmartin

compose/checkpoint.go

@@ -128,7 +128,7 @@ type checkpoint struct {
 
 	SubGraphs map[string]*checkpoint
 
-	InterruptPoints []*interruptStateForPath
+	InterruptPoints []*interruptStateForAddress
 }
 
 type stateModifierKey struct{}

compose/generic_graph.go

@@ -142,7 +142,7 @@ func compileAnyGraph[I, O any](ctx context.Context, g AnyGraph, opts ...GraphCom
 	}
 
 	ctxWrapper := func(ctx context.Context, opts ...Option) context.Context {
-		return initGraphCallbacks(AppendPathStep(ctx, PathStepRunnable, option.graphName), cr.nodeInfo, cr.meta, opts...)
+		return initGraphCallbacks(AppendAddressSegment(ctx, AddressSegmentRunnable, option.graphName), cr.nodeInfo, cr.meta, opts...)
 	}
 
 	rp, err := toGenericRunnable[I, O](cr, ctxWrapper)

compose/graph_run.go

@@ -402,13 +402,13 @@ type interruptTempInfo struct {
 	interruptAfterNodes  []string
 	interruptRerunExtra  map[string]any
 
-	interruptPoints   []*interruptStateForPath
+	interruptPoints   []*interruptStateForAddress
 	interruptContexts []*InterruptCtx
 }
 
 func (it *interruptTempInfo) processInterruptErr(ire *interruptAndRerun) {
-	it.interruptPoints = append(it.interruptPoints, &interruptStateForPath{
-		P: ire.path,
+	it.interruptPoints = append(it.interruptPoints, &interruptStateForAddress{
+		Addr: ire.path,
 		S: &interruptState{
 			Interrupted: true,
 			State:       ire.state,
@@ -656,7 +656,7 @@ func (r *runner) createTasks(ctx context.Context, nodeMap map[string]any, optMap
 		}
 
 		nextTasks = append(nextTasks, &task{
-			ctx:     AppendPathStep(ctx, PathStepNode, nodeKey),
+			ctx:     AppendAddressSegment(ctx, AddressSegmentNode, nodeKey),
 			nodeKey: nodeKey,
 			call:    call,
 			input:   nodeInput,
@@ -716,7 +716,7 @@ func (r *runner) restoreTasks(
 		}
 
 		newTask := &task{
-			ctx:            AppendPathStep(ctx, PathStepNode, key),
+			ctx:            AppendAddressSegment(ctx, AddressSegmentNode, key),
 			nodeKey:        key,
 			call:           call,
 			input:          input,

compose/interrupt.go

@@ -50,28 +50,28 @@ func NewInterruptAndRerunErr(extra any) error {
 }
 
 type wrappedInterruptAndRerun struct {
-	ps    Path
+	ps    Address
 	inner error
 }
 
 func (w *wrappedInterruptAndRerun) Error() string {
-	return fmt.Sprintf("interrupt and rerun at path %s: %s", w.ps.String(), w.inner.Error())
+	return fmt.Sprintf("interrupt and rerun at address %s: %s", w.ps.String(), w.inner.Error())
 }
 
 func (w *wrappedInterruptAndRerun) Unwrap() error {
 	return w.inner
 }
 
 // WrapInterruptAndRerunIfNeeded wraps the InterruptAndRerun error, or the error returned by
-// NewInterruptAndRerunErr, with the current path.
+// NewInterruptAndRerunErr, with the current execution address.
 // If the error is returned by either Interrupt, StatefulInterrupt or CompositeInterrupt,
 // it will be returned as-is without wrapping
-func WrapInterruptAndRerunIfNeeded(ctx context.Context, step PathStep, err error) error {
-	path, _ := GetCurrentPath(ctx)
-	newPath := append(append([]PathStep{}, path...), step)
+func WrapInterruptAndRerunIfNeeded(ctx context.Context, step AddressSegment, err error) error {
+	addr, _ := GetCurrentAddress(ctx)
+	newAddr := append(append([]AddressSegment{}, addr...), step)
 	if errors.Is(err, InterruptAndRerun) {
 		return &wrappedInterruptAndRerun{
-			ps:    newPath,
+			ps:    newAddr,
 			inner: err,
 		}
 	}
@@ -80,7 +80,7 @@ func WrapInterruptAndRerunIfNeeded(ctx context.Context, step PathStep, err error
 	if errors.As(err, &ire) {
 		if ire.path == nil {
 			return &wrappedInterruptAndRerun{
-				ps:    newPath,
+				ps:    newAddr,
 				inner: err,
 			}
 		}
@@ -92,60 +92,60 @@ func WrapInterruptAndRerunIfNeeded(ctx context.Context, step PathStep, err error
 		return ie
 	}
 
-	return fmt.Errorf("failed to wrap error as pathed InterruptAndRerun: %w", err)
+	return fmt.Errorf("failed to wrap error as addressed InterruptAndRerun: %w", err)
 }
 
-// Interrupt creates a special error that signals the graph execution engine to interrupt
-// the current run at the component's specific path and save a checkpoint.
+// Interrupt creates a special error that signals the execution engine to interrupt
+// the current run at the component's specific address and save a checkpoint.
 //
 // This is the standard way for a single, non-composite component to signal a resumable interruption.
 //
-//   - ctx: The context of the running component, used to retrieve the current execution path.
+//   - ctx: The context of the running component, used to retrieve the current execution address.
 //   - info: User-facing information about the interrupt. This is not persisted but is exposed to the
 //     calling application via the InterruptCtx to provide context (e.g., a reason for the pause).
 func Interrupt(ctx context.Context, info any) error {
 	var interruptID string
-	path, pathExist := GetCurrentPath(ctx)
-	if pathExist {
-		interruptID = path.String()
+	addr, addrExist := GetCurrentAddress(ctx)
+	if addrExist {
+		interruptID = addr.String()
 	}
 
-	return &interruptAndRerun{info: info, interruptID: &interruptID, path: path}
+	return &interruptAndRerun{info: info, interruptID: &interruptID, path: addr}
 }
 
-// StatefulInterrupt creates a special error that signals the graph execution engine to interrupt
-// the current run at the component's specific path and save a checkpoint.
+// StatefulInterrupt creates a special error that signals the execution engine to interrupt
+// the current run at the component's specific address and save a checkpoint.
 //
 // This is the standard way for a single, non-composite component to signal a resumable interruption.
 //
-//   - ctx: The context of the running component, used to retrieve the current execution path.
+//   - ctx: The context of the running component, used to retrieve the current execution address.
 //   - info: User-facing information about the interrupt. This is not persisted but is exposed to the
 //     calling application via the InterruptCtx to provide context (e.g., a reason for the pause).
 //   - state: The internal state that the interrupting component needs to persist to be able to resume
 //     its work later. This state is saved in the checkpoint and will be provided back to the component
 //     upon resumption via GetInterruptState.
 func StatefulInterrupt(ctx context.Context, info any, state any) error {
 	var interruptID string
-	path, pathExist := GetCurrentPath(ctx)
-	if pathExist {
-		interruptID = path.String()
+	addr, addrExist := GetCurrentAddress(ctx)
+	if addrExist {
+		interruptID = addr.String()
 	}
 
-	return &interruptAndRerun{info: info, state: state, interruptID: &interruptID, path: path}
+	return &interruptAndRerun{info: info, state: state, interruptID: &interruptID, path: addr}
 }
 
 type interruptAndRerun struct {
 	info        any // for end-user, probably the human-being
 	state       any // for persistence, when resuming, use GetInterruptState to fetch it at the interrupt location
 	interruptID *string
-	path        Path
+	path        Address
 	errs        []*interruptAndRerun
 }
 
 // CompositeInterrupt creates a special error that signals a composite interruption.
 // It is designed for "composite" nodes (like ToolsNode) that manage multiple, independent,
 // interruptible sub-processes. It bundles multiple sub-interrupt errors into a single error
-// that the graph engine can deconstruct into a flat list of resumable points.
+// that the engine can deconstruct into a flat list of resumable points.
 //
 // This function is robust and can handle several types of errors from sub-processes:
 //
@@ -155,7 +155,7 @@ type interruptAndRerun struct {
 //
 //   - An error containing `InterruptInfo` returned by a `Runnable` (e.g., a Graph within a lambda node).
 //
-//   - An error returned by 'WrapInterruptAndRerunIfNeeded' for the legacy InterruptAndRerun error,
+//   - An error returned by \'WrapInterruptAndRerunIfNeeded\' for the legacy InterruptAndRerun error,
 //     and for the error returned by the deprecated NewInterruptAndRerunErr.
 //
 // Parameters:
@@ -178,7 +178,7 @@ type interruptAndRerun struct {
 // the deprecated NewInterruptAndRerunErr function, you must wrap it using WrapInterruptAndRerunIfNeeded first
 // before passing them into this function.
 func CompositeInterrupt(ctx context.Context, info any, state any, errs ...error) error {
-	path, _ := GetCurrentPath(ctx)
+	addr, _ := GetCurrentAddress(ctx)
 	var cErrs []*interruptAndRerun
 	for _, err := range errs {
 		wrapped := &wrappedInterruptAndRerun{}
@@ -228,11 +228,11 @@ func CompositeInterrupt(ctx context.Context, info any, state any, errs ...error)
 
 		return fmt.Errorf("composite interrupt but one of the sub error is not interrupt and rerun error: %w", err)
 	}
-	return &interruptAndRerun{errs: cErrs, path: path, state: state, info: info}
+	return &interruptAndRerun{errs: cErrs, path: addr, state: state, info: info}
 }
 
 func (i *interruptAndRerun) Error() string {
-	return fmt.Sprintf("interrupt and rerun: %v for path: %s", i.info, i.path.String())
+	return fmt.Sprintf("interrupt and rerun: %v for address: %s", i.info, i.path.String())
 }
 
 func IsInterruptRerunError(err error) (any, bool) {
@@ -261,27 +261,27 @@ type InterruptInfo struct {
 	InterruptContexts []*InterruptCtx
 }
 
-// PathStepType defines the type of a segment in an interrupt path.
-type PathStepType string
+// AddressSegmentType defines the type of a segment in an execution address.
+type AddressSegmentType string
 
 const (
-	// PathStepNode represents a segment of a path that corresponds to a graph node.
-	PathStepNode PathStepType = "node"
-	// PathStepTool represents a segment of a path that corresponds to a specific tool call within a ToolsNode.
-	PathStepTool PathStepType = "tool"
-	// PathStepRunnable represents a segment of a path that corresponds to an instance of the Runnable interface.
+	// AddressSegmentNode represents a segment of an address that corresponds to a graph node.
+	AddressSegmentNode AddressSegmentType = "node"
+	// AddressSegmentTool represents a segment of an address that corresponds to a specific tool call within a ToolsNode.
+	AddressSegmentTool AddressSegmentType = "tool"
+	// AddressSegmentRunnable represents a segment of an address that corresponds to an instance of the Runnable interface.
 	// Currently the possible Runnable types are: Graph, Workflow and Chain.
 	// Note that for sub-graphs added through AddGraphNode to another graph is not a Runnable.
-	// So a PathStepRunnable indicates a standalone Root level Graph,
+	// So a AddressSegmentRunnable indicates a standalone Root level Graph,
 	// or a Root level Graph inside a node such as Lambda node.
-	PathStepRunnable PathStepType = "runnable"
+	AddressSegmentRunnable AddressSegmentType = "runnable"
 )
 
-// Path represents a full, hierarchical path to an interrupt point.
-type Path []PathStep
+// Address represents a full, hierarchical address to a point in the execution structure.
+type Address []AddressSegment
 
-// String converts a Path into its unique string representation.
-func (p Path) String() string {
+// String converts an Address into its unique string representation.
+func (p Address) String() string {
 	var sb strings.Builder
 	for i, s := range p {
 		sb.WriteString(string(s.Type))
@@ -294,7 +294,7 @@ func (p Path) String() string {
 	return sb.String()
 }
 
-func (p Path) Equals(other Path) bool {
+func (p Address) Equals(other Address) bool {
 	if len(p) != len(other) {
 		return false
 	}
@@ -306,23 +306,32 @@ func (p Path) Equals(other Path) bool {
 	return true
 }
 
-// PathStep represents a single segment in the hierarchical path to an interrupt point.
-// A sequence of PathSegments uniquely identifies a location within a potentially nested graph structure.
-type PathStep struct {
-	// Type indicates whether this path segment is a graph node or a tool call.
-	Type PathStepType
+func (p Address) DeepCopy() Address {
+	if p == nil {
+		return nil
+	}
+	cpy := make(Address, len(p))
+	copy(cpy, p)
+	return cpy
+}
+
+// AddressSegment represents a single segment in the hierarchical address of an execution point.
+// A sequence of AddressSegments uniquely identifies a location within a potentially nested structure.
+type AddressSegment struct {
+	// Type indicates whether this address segment is a graph node, a tool call, an agent, etc.
+	Type AddressSegmentType
 	// ID is the unique identifier for this segment, e.g., the node's key or the tool call's ID.
 	ID string
 }
 
 // InterruptCtx provides a complete, user-facing context for a single, resumable interrupt point.
 type InterruptCtx struct {
-	// ID is the unique, fully-qualified path to the interrupt point.
-	// It is constructed by joining the individual Path segments, e.g., "node:graph_a;node:tools;tool:tool_call_123".
+	// ID is the unique, fully-qualified address of the interrupt point.
+	// It is constructed by joining the individual Address segments, e.g., "agent:A;node:graph_a;tool:tool_call_123".
 	// This ID should be used when providing resume data via ResumeWithData.
 	ID string
-	// Path is the structured sequence of PathStep segments that leads to the interrupt point.
-	Path Path
+	// Path is the structured sequence of AddressSegment segments that leads to the interrupt point.
+	Path Address
 	// Info is the user-facing information associated with the interrupt, provided by the component that triggered it.
 	Info any
 }
@@ -365,7 +374,7 @@ type subGraphInterruptError struct {
 	Info       *InterruptInfo
 	CheckPoint *checkpoint
 
-	InterruptPoints   []*interruptStateForPath
+	InterruptPoints   []*interruptStateForAddress
 	InterruptContexts []*InterruptCtx
 }